Check the balance of a gift card

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:

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
         Scan	EntryMode: Scanned StoredValueID: Gift card number. ExpiryDate: Expiry date of the gift card.
         Swipe	EntryMode: MagStripe
         MKE	EntryMode: Keyed StoredValueID: 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.

   https://docs.adyen.com/point-of-sale/make-a-payment/gift-cards-terminal-api/query-the-balance#query-the-balance_0

   • JSON
   • Java

   JSON Java

   {
       "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 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.

  {
    "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