POS Transaction Flow: End to End

This guide walks through how a point-of-sale transaction moves through the eCard Systems REST API: getting a token, sending the transaction, reading the response, handling timeouts, and undoing a transaction. Use it alongside the API Reference, which documents every field.

How It Works at a Glance

Authentication is a separate call from the transaction. Your system gets a token once and reuses it. Each transaction is then a single request.

  1. Get a token: POST to the token endpoint with your client ID and secret (OAuth 2.0 client credentials). You get back a bearer token that is valid for 2 hours.
  2. Cache that token and send it in the Authorization: Bearer header on every transaction call until it expires. Don't request a new token for each transaction.
  3. Each transaction is one POST (redeem, load, balance inquiry, and so on) with the token, a unique X-Request-Id header and a JSON body. The response comes back in the same call. There is no separate commit or capture step.
flowchart TD
  A["Get token<br/>POST /auth/token"] --> B["Cache token<br/>reuse for 2 hours"]
  B --> C["POST transaction<br/>Bearer + X-Request-Id"]
  C --> D["401<br/>new token, retry once"]
  C --> E["Timeout or 5xx<br/>retry, same X-Request-Id"]
  C --> F["201 Processed<br/>approved or declined"]
  C --> G["200 Duplicate<br/>original result back"]
  D --> A
  E -- retries run out --> H["Look it up<br/>GET /v1/:id"]
  F -- need to undo --> I["Reverse if needed<br/>POST /v1/:id/reverse"]
  H -- if approved --> I

The token call happens once every two hours at most. Every transaction after that is a single POST, and the X-Request-Id you send ties retries, lookups and reversals back to the original.

Walkthrough: A Guest Pays with a Gift Card

This is the typical sequence at a cashier POS. Each step that calls the API is one request.

  1. The clerk swipes, scans or keys the card. Set entry_mode to match (swipe, barcode, keyed, and so on). At a kiosk, online or in an app, collect the guest's PIN as well.
  2. Optional: check the balance. Call POST /gift/balance-inquiry if your POS shows the balance before tendering.
  3. Redeem. Call POST /gift/redeem with the amount due and a new X-Request-Id. Store that ID with the sale.
    • allow_partial_amount controls what happens when the redeem is for more than the card's balance. For example, the POS sends a redeem for 100.00 on a card that has 50.00:
      • "true": the 50.00 on the card is redeemed, and the response tells the POS that the amount redeemed was 50.00.
      • "false": the redeem is declined with insufficient_funds because the balance is not enough, and nothing is taken off the card.
  4. Read the result. A 201 means the transaction was processed, so check response_status. On approved, apply amount to the check and print balance on the receipt. On declined, show response_message and ask for another tender.
  5. Collect any remainder on another tender, only after the gift card redeem is approved.
  6. If the sale is cancelled, undo the redeem with POST /{id}/reverse, using the redeem's X-Request-Id as {id}.

Walkthrough: Selling or Reloading a Gift Card

  1. Add value: call POST /gift/load with the card number and the amount the guest paid. This works for selling a new card and for reloading an existing one.
  2. Activation is optional: when selling a new card, you can call POST /gift/activate instead of load. Activation turns the card on and adds the value. It is not required.
  3. Read the result the same way: check response_status and print balance on the receipt.
  4. If the sale is cancelled, call POST /{id}/reverse with the original request's X-Request-Id. A cancelled activation can only be undone this way.

To create a digital card with no physical card, use POST /gift/issue-card. This requires the write:cards scope.

Step 1: Get an Access Token

ItemValue
Method and URLPOST https://platform.ecardsystems.com/api/reporting/v1/auth/token
HeaderContent-Type: application/json; charset=utf-8
Bodyclient_id, client_secret, grant_type = client_credentials
Returnsaccess_token (JWT), token_type = Bearer, expires_in = 7200 seconds, scope
{
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "grant_type": "client_credentials"
}
  • Use the platform host: request the token from the platform host, including during sandbox testing. The same token works for sandbox and production. Only the transaction calls go to the sandbox host. Calling the token endpoint on the sandbox host fails.
  • Send credentials in the body: put them in the JSON body, not in a Basic auth header.
  • Scopes: the token endpoint sits under /reporting, but the token also works for transactions. eCard sets the scopes on your application: write:transactions for transactions, read:balances for balance checks, and write:cards if you will issue new cards.
  • Refresh before expiry: get a new token before the current one expires. If a call returns 401, get a new token and retry once. If it returns 401 again, stop and check the MID and MLID (see Step 3).

Step 2: Send the Transaction

EnvironmentBase URL
Sandbox (development and certification)https://sandbox.platform.ecardsystems.com/api/transaction/v1
Production (after certification)https://platform.ecardsystems.com/api/transaction/v1

Every transaction call is a POST to the base URL plus the endpoint path, for example https://sandbox.platform.ecardsystems.com/api/transaction/v1/gift/redeem.

Headers on every transaction call

  • Authorization: Bearer {access_token}
  • Content-Type: application/json
  • X-Request-Id: {unique ID}. Use a new GUID for each new transaction (up to 50 characters: letters, numbers, _ - . : and spaces). This ID is how you retry safely and how you look up or reverse the transaction later.

Request body (redeem example). The fields below come from the API reference schema. The values are placeholders.

{
  "data": {
    "amount": "25.00",
    "card_number": "CARD_NUMBER",
    "entry_mode": "swipe",
    "pin_mode": "verify",
    "pin": "1234",
    "allow_partial_amount": "false",
    "originator_time": "2026-11-17T14:30:00-07:00",
    "originator": {
      "merchant_id": "MID",
      "location_id": "MLID",
      "terminal_id": "TERMINAL_ID",
      "clerk_id": "CLERK_ID"
    }
  }
}
  • amount, card_number, entry_mode, pin_mode and originator.location_id are required. entry_mode is one of keyed, swipe, barcode, qr_code, substitution, stored. pin_mode is one of none, verify, bypass.
  • For the originator, send the eCard MID as merchant_id and the MLID as location_id. eCard provides both for each environment. terminal_id and clerk_id are informational.
  • originator_time is optional. If you send it, use ISO-8601 with an explicit UTC offset. If you leave it out, the current UTC time is used.
  • allow_partial_amount is redeem only. When "true", the host can lower the amount to the card's remaining balance.

Step 3: Read the Response

HTTP statusMeaningWhat to do
201The transaction was processed. It can still be approved or declined.Check response_status: approved, approved_with_reward or declined.
200Duplicate X-Request-Id with the same payload. You get the original result back.Treat it as the original result. No second transaction was created.
400Invalid request, or the same X-Request-Id was reused with a different payloadFix the request, or use a new ID for a new transaction.
401Token invalid or expired, or MID/MLID not authorized for these credentialsGet a new token and retry once. If it fails again, stop retrying and check that the MID and MLID match the environment.
403Token lacks the scope for this endpoint, or sandbox credentials were used on productionAsk eCard to add the scope, or use the correct environment.
422Rejected by business rules, for example pin_mode_not_permittedRead errors and correct the request.
500, 503Server error or service unavailableRetry with the same X-Request-Id (see Step 4).

Key response fields: transaction_id, external_id (your X-Request-Id), transaction_type, response_status, response_code, response_message, amount, request_amount, balance, pin_verification_result.

  • response_status values are lowercase. Compare them case-insensitively.
  • A wrong PIN is not an HTTP error. It returns a 201 decline with response_code = invalid_pin.
  • Redeeming more than a nonzero balance with partial amounts off returns a 201 decline with insufficient_funds. Redeeming against an empty card returns balance_already_zero.

Step 4: Timeouts and Retries

  1. Use a client timeout of about 30 seconds.
  2. On a timeout or 5xx, resend the same request with the same X-Request-Id, backing off exponentially (1s, 2s, 4s, 8s). Within a 2-hour window, a retry never creates a second transaction. If the original went through, you get its result back with a 200.
  3. If retries run out, look up the transaction with GET /v1/{X-Request-Id}. If it was approved and you need to undo it, reverse it (see Step 5). If it is not found, it never processed.

Step 5: Undo a Transaction

To undo a transaction, call POST /{id}/reverse, using the original transaction's X-Request-Id as {id}. This reverses the full amount, is linked to the original, and works once. For the void endpoints, partial adjustments and how to check whether a transaction was reversed, see Voids and Reversals.

Endpoint Reference

All paths are relative to the base URL in Step 2. All are POST unless noted.

TransactionPath
Activation/gift/activate
Load/gift/load
Redeem/gift/redeem
Balance Inquiry (recommended)/gift/balance-inquiry
Reverse a transaction/{id}/reverse (see Voids and Reversals)
Look up a transactionGET /{id}
Issue a new digital card/gift/issue-card (requires write:cards)

Use /gift/balance-inquiry for balance checks. It records a transaction and appears in merchant history. The root /balance-inquiry is a read-only lookup that leaves no record.

Design Notes

  • One card per request. There are no multi-card calls. If a guest cancels partway through a multi-card payment, reverse the cards that already went through.
  • Split tender: process the gift card first and wait for approval before charging the remainder to another tender.
  • PIN: guest-facing redemptions (kiosks, online ordering, websites, apps) must send pin_mode = verify with the PIN. PIN is optional at a cashier-operated POS. For a card with no PIN on file, send pin as null.
  • No transaction webhooks. Results come back only in the synchronous response.
  • No reporting API. The history endpoints are for one-off lookups. Merchants use the eCard portal for reporting.

Did this page help you?