Which Balance Inquiry To Use
This article is to help describe the differences between the balance inquiry calls in the Gift service and the Transaction service.
Choosing a Balance Inquiry Endpoint
The eCard API exposes two ways to check the balance on a card:
- Gift Balance Inquiry (Recommended) —
POST /v1/gift/balance-inquiry - Balance Inquiry —
POST /v1/balance-inquiry
They look similar and take the same request body, but they behave differently. This guide explains the difference and which one to reach for.
RecommendationFor almost every integration, use Gift Balance Inquiry (
/v1/gift/balance-inquiry). It returns a single, easy-to-read balance and records a transaction you can look up later, which makes support and troubleshooting far simpler.
Quick comparison
| Gift Balance Inquiry (Recommended) | Balance Inquiry | |
|---|---|---|
| Endpoint | POST /v1/gift/balance-inquiry | POST /v1/balance-inquiry |
| Success status | 201 Created | 200 OK |
| Creates a transaction? | Yes | No |
| Balance in the response | A single balance value for the Gift purse | A balances object with every purse on the card |
| Approved / declined result | Yes — response_status, response_code, response_message | Not applicable (it is a read-only lookup) |
| Appears in transaction history | Yes | No |
| Can be found later by Request Id | Yes | No |
| Best for | Almost all gift card integrations | The rare case where you must not create a transaction |
Gift Balance Inquiry (Recommended)
POST /v1/gift/balance-inquiry
This endpoint processes a balance inquiry as a transaction against the Gift scheme. On success it returns 201 Created, and the response describes a single, completed transaction.
Why we recommend it:
- The response is simple to read. You get one
balancevalue for the Gift purse, alongside a clearresponse_status(approvedordeclined) and a human-readableresponse_message. There is no purse structure to navigate — the number you want is right there. - It creates a transaction, which makes troubleshooting easier. Because the inquiry is recorded, it receives a
transaction_idand shows up in the card's transaction history. If a balance ever looks wrong, you (or our support team) can find the exact inquiry, see when it happened, and see what was returned. You can also retrieve it later with Lookup Transaction by Request Id.
Example request
Send the same card request body used across the transaction endpoints, with a unique X-Request-Id header.
{
"data": {
"entry_mode": "keyed",
"card_number": "603912345678",
"pin_mode": "none",
"originator": {
"location_id": "STORE-001"
}
}
}Example response (201 Created)
201 Created){
"data": {
"transaction_id": "b3f1c2a4-9d0e-4c8b-a1f2-7e6d5c4b3a21",
"external_id": "d9e8f7a6-1b2c-3d4e-5f60-718293a4b5c6",
"entry_mode": "keyed",
"card_number": "603912345678",
"pin_mode": "none",
"pin_verification_result": "none",
"transaction_type": "gift_balance_inquiry",
"response_status": "approved",
"response_code": "transaction_approved",
"response_message": "Approved",
"balance": "25.00"
}
}
The Gift purse balance is the top-levelbalancefield.originator,target, and timestamp fields are also included in the full response but are omitted here for readability.
Balance Inquiry
POST /v1/balance-inquiry
This endpoint looks up balances without creating a transaction. On success it returns 200 OK and a balances object containing every purse associated with the card.
Because nothing is recorded, there is no transaction_id, no approved/declined result, and nothing to find in transaction history afterward. That makes it harder to troubleshoot after the fact, and it means you have to read the balance you want out of the balances object.
Example response (200 OK)
200 OK){
"data": {
"card_number": "603912345678",
"system_time": "2025-07-09T14:32:00Z",
"balances": {
"gift": "25.00",
"gift_rewards": "0.00",
"loyalty": "0.00",
"loyalty_rewards": "0.00",
"discount": "0.00",
"promotional": "0.00",
"punch": "0.00",
"punch_rewards": "0.00"
}
}
}When to use it
Reach for /v1/balance-inquiry only when you specifically need to check a balance without leaving a transaction record. This is uncommon. If you are not sure whether your situation calls for it, it almost certainly does not — use Gift Balance Inquiry instead.
This endpoint also returns balances for every purse on the card in one call, so it can be useful if you genuinely need to read several purses at once. For a gift-only integration, the single-value Gift Balance Inquiry response is simpler.
How to choose
- Building a gift card integration? Use Gift Balance Inquiry (
/v1/gift/balance-inquiry). This is the right choice for the vast majority of integrators. - Need to check a balance without recording a transaction? Use Balance Inquiry (
/v1/balance-inquiry). Expect this to be rare.
If you are unsure, start with Gift Balance Inquiry. The recorded transaction and the simpler response will save you time when you need to verify behavior or ask us for help.
Updated 26 days ago