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
      • 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 cash register.
      • POIID: the unique ID of the terminal that you want to send this request to. Format: [device model]-[serial number].
    • BalanceInquiryRequest containing:

      • 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
          Scan
          • EntryMode: Scanned
          • StoredValueID: gift card number.
          • ExpiryDate: expiry date of the gift card.
          Swipe
          • EntryMode: MagStripe
          • StoredValueID: include this parameter but don't provide a value.
          MKE
          • 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, see 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 response as an event 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, see 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

See also