Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale icon

Check the balance of a gift card

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.

Before you begin

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

Make a balance inquiry

To see the funds remaining on a gift card:

  1. 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.
  2. 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: givex, svs, valuelink, or any Intersolve-supported card type.
        • IdentificationType: PAN
        • EntryMode, StoredValueID and ExpiryDate: These parameters depend on the card entry method you are using.

          Card entry Parameters
          • EntryMode: Scanned
          • StoredValueID: Gift card number.
          • ExpiryDate: Expiry date of the gift card.
          • EntryMode: MagStripe
          • StoredValueID: Include this parameter but don't provide a value.
          • EntryMode: Keyed
          • StoredValueID: Include this parameter but don't provide a value.

    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.

    String serviceID = "YOUR_UNIQUE_ATTEMPT_ID";
    String saleID = "YOUR_CASH_REGISTER_ID";
    SaleToPOIRequest saleToPOIRequest = new SaleToPOIRequest();
    MessageHeader messageHeader = new MessageHeader();
    messageHeader.setMessageClass( MessageClassType.SERVICE );
    messageHeader.setMessageCategory( MessageCategoryType.BALANCE_INQUIRY );
    messageHeader.setMessageType( MessageType.REQUEST );
    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.setIdentificationType( IdentificationType.PAN );
    storedValueAccountID.getEntryMode().add( EntryModeType.SCANNED );

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: 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.


Next steps

See also