To check the funds remaining on an activated gift card, make a balance request.
Before you begin
Before you make any gift card transactions, make sure that you have:
- Built an integration that can make a payment.
- Completed the onboarding process with your gift card provider.
- Added the payment method to your Adyen account.
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 request to a Terminal API endpoint, specifying:
-
MessageHeader
: This follows the standardMessageHeader
structure, explained in Terminal API fundamentals, which includes:ProtocolVersion
: 3.0MessageCategory
: BalanceInquiryMessageType
: RequestSaleID
: Your unique ID for the cash register.ServiceID
: Your unique ID for this transaction attempt. This needs to be unique within the last 48 hours.POIID
: Unique ID of the terminal. This indicates which terminal the transaction will be routed to.
-
BalanceInquiryRequest
: The request body for the balance request must include:PaymentAccountReq.PaymentInstrumentData.PaymentInstrumentType
: StoredValue-
PaymentAccountReq.PaymentInstrumentData.StoredValueAccountID
: The gift card details:StoredValueAccountType
: GiftCardStoredValueProvider
: The gift card issuer: givex, svs, valuelink, or any Intersolve-supported card type.IdentificationType
: PAN-
EntryMode
,StoredValueID
andExpiryDate
: These parameters depend on the card entry method you are using.Card entry Parameters Scan EntryMode
: ScannedStoredValueID
: Gift card number.ExpiryDate
: Expiry date of the gift card.
Swipe EntryMode
: MagStripe
MKE EntryMode
: KeyedStoredValueID
: xxxxxxxxxxxxxxxxxxx.
The example below shows how you would request the balance of a scanned gift card.
For more information on the Terminal API request structure, refer to the Terminal API fundamentals.
{ "SaleToPOIRequest":{ "MessageHeader":{ "ProtocolVersion":"3.0", "MessageClass":"Service", "MessageCategory":"BalanceInquiry", "MessageType":"Request", "ServiceID":"9266", "SaleID":"POSSystemID12345", "POIID":"V400m-324688179" }, "BalanceInquiryRequest":{ "PaymentAccountReq":{ "PaymentInstrumentData":{ "PaymentInstrumentType":"StoredValue", "StoredValueAccountID":{ "StoredValueAccountType":"GiftCard", "StoredValueProvider":"svs", "IdentificationType":"PAN", "EntryMode":[ "Scanned" ], "StoredValueID":"6006491260550218066", "ExpiryDate":"1122" } } } } } }
String serviceID = "YOUR_UNIQUE_ATTEMPT_ID"; String saleID = "YOUR_CASH_REGISTER_ID"; String POIID = "YOUR_TERMINAL_ID"; SaleToPOIRequest saleToPOIRequest = new SaleToPOIRequest(); MessageHeader messageHeader = new MessageHeader(); messageHeader.setProtocolVersion("3.0"); messageHeader.setMessageClass( MessageClassType.SERVICE ); messageHeader.setMessageCategory( MessageCategoryType.BALANCE_INQUIRY ); messageHeader.setMessageType( MessageType.REQUEST ); messageHeader.setServiceID(serviceID); messageHeader.setSaleID(saleID); messageHeader.setPOIID(POIID); saleToPOIRequest.setMessageHeader(messageHeader); BalanceInquiryRequest balanceInquiryRequest = new BalanceInquiryRequest(); PaymentAccountReq paymentAccountReq = new PaymentAccountReq(); PaymentInstrumentData paymentInstrumentData = new PaymentInstrumentData(); paymentInstrumentData.setPaymentInstrumentType( PaymentInstrumentType.STORED_VALUE ); StoredValueAccountID storedValueAccountID = new StoredValueAccountID(); storedValueAccountID.setStoredValueAccountType( StoredValueAccountType.GIFT_CARD ); storedValueAccountID.setStoredValueProvider("svs"); storedValueAccountID.setIdentificationType( IdentificationType.PAN ); storedValueAccountID.getEntryMode().add( EntryModeType.SCANNED ); storedValueAccountID.setStoredValueID("6006491260550218066"); storedValueAccountID.setExpiryDate("1122"); paymentInstrumentData.setStoredValueAccountID(storedValueAccountID); paymentAccountReq.setPaymentInstrumentData(paymentInstrumentData); balanceInquiryRequest.setPaymentAccountReq(paymentAccountReq); saleToPOIRequest.setBalanceInquiryRequest(balanceInquiryRequest); terminalAPIRequest.setSaleToPOIRequest(saleToPOIRequest);
-
Your integration receives the balance of the gift card in the response.
Balance inquiry response
Once processed, your integration receives a response containing the balance of the gift card. This is provided in a synchronous API response, unless your integration uses asynchronous cloud communications.
If your integration uses asynchronous cloud communications, you receive the balance in a TENDER_FINAL display notification.
If the balance request is successful:
-
You receive a response with a
BalanceInquiryResponse
object that includes:Response.Result
: SuccessPaymentAccountStatus.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 98.75 GBP.
For more information on the Terminal API response structure, refer to the Terminal API fundamentals.
{ "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" } } }