Transactions/createBalanceInquiry

Balance Inquiry

Preview

Check the available balance on a prepaid or gift card.

POST/v1/terminal/balance-inquiry

Preview contract only. A balance must come from an acquiring-engine host integration. Until that capability is configured this endpoint returns 503; it never fabricates an approved zero balance.

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.

createBalanceInquiry

curl https://api.kepapay.co/v1/terminal/balance-inquiry \ -H "X-Api-Key: $KEPA_SECRET_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"type": "BALANCE_INQUIRY","amount": 0,"currency": "NZD","entryMode": "AUTO"}'