Transactions/createBalanceInquiry

Balance Inquiry

Check the available balance on a prepaid or gift card.

POST/v1/transaction/balance-inquiry

Look up the available balance on a card. Typically used for prepaid, gift, and closed-loop stored-value cards. The card must be presented at the terminal — the balance comes back in the amount field of the response.

Request body

application/json

typeenumrequired

Transaction type.

SALEPRE_AUTHPRE_AUTH_COMPLETEREFUNDVOIDCARD_READBALANCE_INQUIRY

Example: "SALE"

amountintegerrequired

Transaction amount in minor units. For a $25.00 NZD transaction, send 2500. Use 0 for card-read and balance-inquiry.

Example: 2500

currencystringrequired

ISO 4217 currency code.

Example: "NZD"

cashbackAmountinteger

Cashback amount in minor units (sale transactions only).

Example: 0

entryModeenum

Card entry mode preference. AUTO lets the terminal accept any method.

CONTACTLESSCONTACTAUTO

Example: "AUTO"

referenceIdstring

POS-assigned reference identifier for this transaction (max 64 chars).

Example: "POS-INV-20260328-001"

originalTransactionIdstring

Required for refund, void, and pre-auth completion. The transactionId of the original transaction being referenced.

tipAmountinteger

Tip amount in minor units.

Example: 0

metadataobject

Arbitrary string key-value metadata attached to the transaction. Echoed in the response and available in reconciliation exports. Max 20 keys, 256 chars per value.

Response

application/json

transactionIdstringrequired

Unique identifier for this transaction.

Example: "txn_01JQXYZ123456"

statusenumrequired

Terminal or in-flight state of the transaction.

APPROVEDDECLINEDCANCELLEDERRORREVERSEDPENDING_ONLINEPENDING_COMPLETION

typeenumrequired

Transaction type (echoed from the request).

SALEPRE_AUTHPRE_AUTH_COMPLETEREFUNDVOIDCARD_READBALANCE_INQUIRY

amountintegerrequired

Transaction amount in minor units.

Example: 2500

currencystringrequired

ISO 4217 currency code.

Example: "NZD"

tipAmountinteger

Tip amount in minor units.

Example: 0

authorizationCodestring

Authorization code from the issuer.

Example: "A12345"

responseCodestring

ISO 8583 response code. "00" = approved.

Example: "00"

cardSchemeenum

Card scheme / network.

VISAMASTERCARDAMEXDISCOVERJCBUNIONPAYEFTPOSOTHER

maskedPanstring

Masked primary account number. Only the last 4 digits are visible; all other positions are replaced with asterisks.

Example: "************1234"

entryModeenum

Actual card entry mode used.

CONTACTLESSCONTACTMAGSTRIPEMANUAL

aidstring

EMV Application Identifier (AID) hex string.

Example: "A0000000031010"

applicationLabelstring

EMV application label.

Example: "Visa Credit"

cryptogramTypeenum

Type of cryptogram generated by the card. TC = Transaction Certificate (offline approved), ARQC = online auth required, AAC = declined.

TCARQCAAC

tvrstring

Terminal Verification Results (10-character hex).

Example: "0000000000"

cvmResultenum

Cardholder Verification Method used.

PINSIGNATURECDCVMNO_CVMFAILED

referenceIdstring

POS-assigned reference identifier (echoed).

rrnstring

Retrieval Reference Number.

Example: "262803141422"

timestampstring · ISO 8601required

Transaction timestamp (ISO 8601).

Example: "2026-03-28T09:14:22Z"

receiptDataobject

Structured receipt data for rendering cardholder and merchant receipts. See the Receipt Requirements page for rendering rules.

merchantNamestring

Merchant trading name.

Example: "Atlas Coffee"

merchantIdstring

Acquirer-assigned merchant identifier (MID).

Example: "MID123456789"

terminalIdstring

Acquirer-assigned terminal identifier (TID).

Example: "TID-00012345"

transactionIdstring

Transaction identifier.

dateTimestring · ISO 8601

Local date and time of the transaction.

cardSchemestring

Card scheme name for the receipt (e.g. 'VISA').

maskedPanstring

Masked PAN for receipt display (last 4 only).

Example: "************1234"

applicationLabelstring

EMV application label (e.g. 'Visa Credit').

Example: "Visa Credit"

aidstring

EMV Application Identifier.

Example: "A0000000031010"

authorizationCodestring

Issuer authorization code.

amountinteger

Transaction amount in minor units.

Example: 2500

tipAmountinteger

Tip amount in minor units.

Example: 0

totalAmountinteger

Total amount (amount + tip) in minor units.

Example: 2500

entryModestring

Card entry mode (CONTACTLESS, CONTACT, etc.).

cvmPerformedenum

Cardholder verification method used.

PINSIGNATURECDCVMNO_CVMFAILED

approvalStatusenum

APPROVED or DECLINED.

APPROVEDDECLINED

chipDataobject

EMV chip data for POS-side acquirer routing. Only populated in granular mode (status = PENDING_ONLINE).

emvTagsobject

Map of EMV tag hex identifiers to hex-encoded values. Common tags: 9F26 (Application Cryptogram), 9F27 (Cryptogram Info Data), 9F10 (Issuer Application Data), 9F37 (Unpredictable Number), 9F36 (ATC), 9C (Transaction Type), 9F02 (Amount Authorized), 5F2A (Transaction Currency Code), 9A (Transaction Date), 9F1A (Terminal Country Code).

encryptedPinBlockstringnullable

Encrypted PIN block (hex), or null if PIN was not entered.

pinKsnstringnullable

Key Serial Number for the PIN encryption key (hex).

pinBlockFormatenumnullable

PIN block format identifier.

ISO_0ISO_1ISO_3ISO_4

metadataobject

Arbitrary key-value metadata echoed from the request.

commerce-api/openapi.yaml · createBalanceInquiry