--- title: "Check the balance of a gift card" description: "Query the balance of a gift card at the point of sale." url: "https://docs.adyen.com/point-of-sale/alternative-payment-methods/gift-cards-terminal-api/query-the-balance" source_url: "https://docs.adyen.com/point-of-sale/alternative-payment-methods/gift-cards-terminal-api/query-the-balance.md" canonical: "https://docs.adyen.com/point-of-sale/alternative-payment-methods/gift-cards-terminal-api/query-the-balance" last_modified: "2019-10-01T11:43:00+02:00" language: "en" --- # Check the balance of a gift card Query the balance of a gift card at the point of sale. [View source](/point-of-sale/alternative-payment-methods/gift-cards-terminal-api/query-the-balance.md) You can check the funds remaining on an [activated gift card](/point-of-sale/gift-cards-terminal-api/activate), by making a balance request. This allows you to verify the gift card's value before a transaction and determine if a partial payment is needed. ## Requirements Before you begin, take into account the following requirements, limitations, and preparations. | Requirement | Description | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | A [Terminal API](/point-of-sale/design-your-integration/terminal-api) integration with payment terminals. | | **Setup steps** | Before you begin:- [Add the payment method to your Adyen account](/point-of-sale/what-we-support/payment-methods#add-payment-methods-to-your-account). - Complete the onboarding process with the gift card provider. | ## Make a balance inquiry To see the funds remaining on a gift card: 1. Determine the [card entry method](/point-of-sale/gift-cards-terminal-api#card-entry): * 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 [Terminal API](/point-of-sale/design-your-integration/terminal-api) balance inquiry request, specifying: * The standard [`SaleToPOIRequest.MessageHeader` ](/point-of-sale/design-your-integration/terminal-api#request-message-header)object, with `MessageClass` set to **Service** and `MessageCategory` set to **BalanceInquiry**. | Parameter | Required | Description | | ----------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ProtocolVersion` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **3.0** | | `MessageClass` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Service** | | `MessageCategory` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **BalanceInquiry** | | `MessageType` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Request** | | `ServiceID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | 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` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Your unique ID for the POS system component to send this request from. | | `POIID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The unique ID of the terminal to send this request to. Format: *\[device model]-\[serial number]*. | * The [BalanceInquiryRequest.PaymentAccountReq.PaymentInstrumentData](https://docs.adyen.com/api-explorer/terminal-api/latest/post/balanceinquiry#request-PaymentAccountReq-PaymentInstrumentData) object with: | Parameter | Required | Description | | ----------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `ProtectedCardData` | | Optional secondary security (SSC) code for SVS gift cards. The SSC allows up to 8 digits. For example, `ssc=1111`.If the secondary security code is required, encode it to Base64 and pass the resulting string. For example, `{"ssc=1111"}` needs to be passed as `"ProtectedCardData": "eyJzc2MiOiIxMTExIn0="` | | `PaymentInstrumentType` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **StoredValue** | | `StoredValueAccountID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The gift card details:- `StoredValueAccountType`: **GiftCard** - `StoredValueProvider`: the gift card issuer: **givex**, **svs**, **valuelink**, or **[any Intersolve-supported card type](/payment-methods/gift-cards#supported-gift-cards)**. - `IdentificationType`: **PAN** - `EntryMode`, `StoredValueID` and `ExpiryDate`: these parameters depend on the [card entry method](/point-of-sale/gift-cards-terminal-api#card-entry) you are using. See the following table. | | 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 do not provide a value. | | MKE | * `EntryMode`: **Keyed** * `StoredValueID`: include this parameter but do not provide a value. | The example below shows how to check the balance for a scanned gift card. It includes an optional `ProtectedCardData` field required for stored value solution gift cards with the SSC converted to a Base64-encoded string. #### JSON ```json { "SaleToPOIRequest":{ "MessageHeader":{ "ProtocolVersion":"3.0", "MessageClass":"Service", "MessageCategory":"BalanceInquiry", "MessageType":"Request", "ServiceID":"9266", "SaleID":"POSSystemID12345", "POIID":"V400m-324688179" }, "BalanceInquiryRequest":{ "PaymentAccountReq":{ "PaymentInstrumentData":{ "ProtectedCardData": "eyJzc2MiOiIxMTExIn0=", "PaymentInstrumentType":"StoredValue", "StoredValueAccountID":{ "StoredValueAccountType":"GiftCard", "StoredValueProvider":"svs", "IdentificationType":"PAN", "EntryMode":[ "Scanned" ], "StoredValueID":"6006491260550218066", "ExpiryDate":"1122" } } } } } } ``` #### Java ```java 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); ``` 3. In the [BalanceInquiryResponse](https://docs.adyen.com/api-explorer/terminal-api/latest/post/balanceinquiry#responses-200-Response), check the following: * `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 GBP 98.75. ```json { "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" } } } ``` ## See also * [Gift cards and other stored value cards](/point-of-sale/gift-cards-terminal-api) * [Activate a gift card](/point-of-sale/gift-cards-terminal-api/activate) * [Load funds to a gift card](/point-of-sale/gift-cards-terminal-api/load-a-balance) * [Make a gift card payment](/point-of-sale/gift-cards-terminal-api/payment)