Check the balance of a gift card

To check the funds remaining on an activated gift card, make a balance request.

Requirements

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:

     Parameter	Required	Description
     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 POS system component to send this request from.
     POIID		The unique ID of the terminal to send this request to. Format: [device model]-[serial number].

   • BalanceInquiryRequest.PaymentAccountReq.PaymentInstrumentData. This includes:

     Parameter	Required	Description
     ProtectedCardData		Optional secondary security (SSC) code for SVS gift cards. The SSC allows up to 8 digits. For example, ssc=1111. Needs to get encoded to Base64.
     PaymentInstrumentType		StoredValue
     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. See the following table.

     If the secondary security code is required, encode it to Base64, and pass the resulting string as in the example for {"ssc=1111"}:
     "ProtectedCardData": "eyJzc2MiOiIxMTExIn0=

     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.

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 GBP 98.75.

  See the BalanceInquiryResponse API reference.

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