You can check the funds remaining on an activated gift card, by making a balance request. This allows you to verify the gift card's value before a transaction and determine if a partial payment is needed.
Requirements
Before you begin, take into account the following requirements, limitations, and preparations.
Requirement | Description |
---|---|
Integration type | A Terminal API integration with payment terminals. |
Setup steps | Before you begin:
|
Make a balance inquiry
To see the funds remaining on a gift card:
-
Determine the card entry method:
- If you want to scan the card, do that first and use the obtained card details in your request.
- If you want to swipe the card or use manual keyed entry (MKE), send the request first. The payment terminal will show a prompt to swipe the card or enter the card details.
-
Make a POST Terminal API request, specifying:
-
MessageHeader
: this follows the standardMessageHeader
structure, explained in Terminal API fundamentals, which includes:Parameter Required Description ProtocolVersion
3.0 MessageClass
Service MessageCategory
BalanceInquiry MessageType
Request ServiceID
Your unique ID for this request, consisting of 1-10 alphanumeric characters. Must be unique within the last 48 hours for the terminal ( POIID
) being used.SaleID
Your unique ID for the POS system component to send this request from. POIID
The unique ID of the terminal to send this request to. Format: [device model]-[serial number]. -
BalanceInquiryRequest.PaymentAccountReq.PaymentInstrumentData
. This includes:Parameter Required Description ProtectedCardData
Optional secondary security (SSC) code for SVS gift cards. The SSC allows up to 8 digits. For example, ssc=1111
. Needs to get encoded to Base64.PaymentInstrumentType
StoredValue StoredValueAccountID
The gift card details: StoredValueAccountType
: GiftCardStoredValueProvider
: the gift card issuer: givex, svs, valuelink, or any Intersolve-supported card type.IdentificationType
: PANEntryMode
,StoredValueID
andExpiryDate
: these parameters depend on the card entry method you are using. See the following table.
If the secondary security code is required, encode it to Base64, and pass the resulting string as in the example for
{"ssc=1111"}
:
"ProtectedCardData": "eyJzc2MiOiIxMTExIn0=
Card entry Parameters Scan EntryMode
: ScannedStoredValueID
: gift card number.ExpiryDate
: expiry date of the gift card.
Swipe EntryMode
: MagStripeStoredValueID
: include this parameter but do not provide a value.
MKE EntryMode
: KeyedStoredValueID
: include this parameter but do not provide a value.
The example below shows how to check the balance for a scanned gift card. It includes an optional
ProtectedCardData
field required for stored value solution gift cards with the SSC converted to a Base64-encoded string.See the BalanceInquiryRequest API reference.
-
-
In the
BalanceInquiryResponse
, check the following:PaymentAccountStatus.CurrentBalance
: the value of the gift card balance.PaymentAccountStatus.Currency
: the currency of the gift card balance.
The example below indicates that the gift card has a balance of GBP 98.75.
{ "SaleToPOIResponse":{ "BalanceInquiryResponse":{ "Response":{ "Result":"Success" }, "PaymentAccountStatus":{ "CurrentBalance":98.75, "PaymentAcquirerData":{ "AcquirerPOIID":"V400m-324688179" }, "Currency":"GBP" } }, "MessageHeader":{ "ProtocolVersion":"3.0", "SaleID":"POSSystemID12345", "MessageClass":"Service", "MessageCategory":"BalanceInquiry", "ServiceID":"9266", "POIID":"V400m-324688179", "MessageType":"Response" } } }
See the BalanceInquiryResponse API reference.