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.
- 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.
- Cache that token and send it in the
Authorization: Bearerheader on every transaction call until it expires. Don't request a new token for each transaction. - Each transaction is one POST (redeem, load, balance inquiry, and so on) with the token, a unique
X-Request-Idheader 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.
- The clerk swipes, scans or keys the card. Set
entry_modeto match (swipe,barcode,keyed, and so on). At a kiosk, online or in an app, collect the guest's PIN as well. - Optional: check the balance. Call
POST /gift/balance-inquiryif your POS shows the balance before tendering. - Redeem. Call
POST /gift/redeemwith the amount due and a newX-Request-Id. Store that ID with the sale.allow_partial_amountcontrols 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 withinsufficient_fundsbecause the balance is not enough, and nothing is taken off the card.
- Read the result. A 201 means the transaction was processed, so check
response_status. Onapproved, applyamountto the check and printbalanceon the receipt. Ondeclined, showresponse_messageand ask for another tender. - Collect any remainder on another tender, only after the gift card redeem is approved.
- If the sale is cancelled, undo the redeem with
POST /{id}/reverse, using the redeem'sX-Request-Idas{id}.
Walkthrough: Selling or Reloading a Gift Card
- Add value: call
POST /gift/loadwith the card number and the amount the guest paid. This works for selling a new card and for reloading an existing one. - Activation is optional: when selling a new card, you can call
POST /gift/activateinstead of load. Activation turns the card on and adds the value. It is not required. - Read the result the same way: check
response_statusand printbalanceon the receipt. - If the sale is cancelled, call
POST /{id}/reversewith the original request'sX-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
| Item | Value |
|---|---|
| Method and URL | POST https://platform.ecardsystems.com/api/reporting/v1/auth/token |
| Header | Content-Type: application/json; charset=utf-8 |
| Body | client_id, client_secret, grant_type = client_credentials |
| Returns | access_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:transactionsfor transactions,read:balancesfor balance checks, andwrite:cardsif 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
| Environment | Base 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/jsonX-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_modeandoriginator.location_idare required.entry_modeis one ofkeyed,swipe,barcode,qr_code,substitution,stored.pin_modeis one ofnone,verify,bypass.- For the originator, send the eCard MID as
merchant_idand the MLID aslocation_id. eCard provides both for each environment.terminal_idandclerk_idare informational. originator_timeis 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_amountis redeem only. When"true", the host can lower the amount to the card's remaining balance.
Step 3: Read the Response
| HTTP status | Meaning | What to do |
|---|---|---|
| 201 | The transaction was processed. It can still be approved or declined. | Check response_status: approved, approved_with_reward or declined. |
| 200 | Duplicate X-Request-Id with the same payload. You get the original result back. | Treat it as the original result. No second transaction was created. |
| 400 | Invalid request, or the same X-Request-Id was reused with a different payload | Fix the request, or use a new ID for a new transaction. |
| 401 | Token invalid or expired, or MID/MLID not authorized for these credentials | Get a new token and retry once. If it fails again, stop retrying and check that the MID and MLID match the environment. |
| 403 | Token lacks the scope for this endpoint, or sandbox credentials were used on production | Ask eCard to add the scope, or use the correct environment. |
| 422 | Rejected by business rules, for example pin_mode_not_permitted | Read errors and correct the request. |
| 500, 503 | Server error or service unavailable | Retry 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_statusvalues 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 returnsbalance_already_zero.
Step 4: Timeouts and Retries
- Use a client timeout of about 30 seconds.
- 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. - 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.
| Transaction | Path |
|---|---|
| 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 transaction | GET /{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=verifywith the PIN. PIN is optional at a cashier-operated POS. For a card with no PIN on file, sendpinasnull. - 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.
Updated 1 day ago
