Search

Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale icon

Check a gift card balance

Query the balance of a gift card at the point of sale.

To check the funds remaining on an activated gift card, make a balance request. When the balance request is processed, you receive a response specifying the funds remaining on the gift card.

Before you begin

Before you make any gift card transactions, make sure that you have:

Step 1: Request gift card balance

To request the balance of a gift card:

  • Make a POST request to a Terminal API endpoint, specifying:

    • MessageHeader: This follows the standard MessageHeader structure, explained in Terminal API fundamentals, which includes:

      • ProtocolVersion: 3.0
      • MessageCategory: BalanceInquiry
      • MessageType: Request
      • SaleID: 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: GiftCard
        • StoredValueProvider: The gift card issuer. Accepted values: givex, svs, or valuelink
        • ExpiryDate: The gift card expiry date.
        • EntryMode: MagStripe or Scanned
        • IdentificationType: PAN or BarCode
        • StoredValueID: The gift card number.

    The example below shows how you would request the balance of the gift card with the ID 9826150911219687.

    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",
                            "EntryMode":[
                                "Scanned"
                            ],
                            "IdentificationType":"PAN",
                            "StoredValueID":"9826150911219687",
                            "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.getEntryMode().add( EntryModeType.SCANNED );
    storedValueAccountID.setStoredValueProvider("svs");
    storedValueAccountID.setIdentificationType( IdentificationType.PAN );
    storedValueAccountID.setStoredValueID("9826150911219687");
    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.

Step 2: Receive gift card balance

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 that contains a BalanceInquiryResponse object. This includes:

    • Response.Result: Success
    • 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 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"
            }
        }
    }

Next steps