Query the balance

Outlines querying the balance of a gift card used by a shopper.


Not all operations are available for each type of gift card. For an overview of supported features for the different types, see Gift Card Overview

Endpoint

The URL used to send  Terminal API  messages depends on your type of implementation. For more information on the architectures available, see the Terminal API Overview .

Request

For a list of BalanceInquiryRequest fields, see BalanceInquiryRequest fields.

The elements of a gift card balance inquiry request are wrapped in a BalanceInquiryRequest envelope.

The SaleID and ServiceID in the MessageHeader should be unique. SaleID and ServiceID combinations are rejected if used recently, within 48 hours.

The fields described below are the basic fields you specify when making a BalanceInquiryRequest call to the Terminal API.

BalanceInquiryRequest
{
   "SaleToPOIRequest":{
      "MessageHeader":{
         "ProtocolVersion":"3.0",
         "MessageClass":"Service",
         "MessageCategory":"BalanceInquiry",
         "MessageType":"Request",
         "ServiceID":"0326112814",
         "SaleID":"POSSystemID12345",
         "POIID":"MX925-286240330"
      },
      "BalanceInquiryRequest":{
         "PaymentAccountReq":{
            "PaymentInstrumentData":{
               "PaymentInstrumentType":"StoredValue",
               "StoredValueAccountID":{
                  "StoredValueAccountType":"GiftCard",
                  "EntryMode":[
                     "Scanned"
                  ],
                  "StoredValueProvider":"goldsmiths",
                  "IdentificationType":"PAN",
                  "StoredValueID":"9826150911219687",
                  "ExpiryDate":"1117"
               }
            }
         }
      }
   }
}

Response

For a list of BalanceInquiryResponse fields, see BalanceInquiryResponse fields.

You receive a response with the following fields:

BalanceInquiryResponse
{
   "SaleToPOIResponse":{
      "BalanceInquiryResponse":{
         "Response":{
            "Result":"Success"
         },
         "PaymentAccountStatus":{
            "CurrentBalance":9875,
            "PaymentAcquirerData":{
               "AcquirerPOIID":"MX925-286240330"
            },
            "Currency":"GBP"
         }
      },
      "MessageHeader":{
         "ProtocolVersion":"3.0",
         "SaleID":"POSSystemID12345",
         "MessageClass":"Service",
         "MessageCategory":"BalanceInquiry",
         "ServiceID":"0326112814",
         "POIID":"MX925-286240330",
         "MessageType":"Response"
      }
   }
}

Not all data in a payment response will always be available. The availability of some data depends on an internet connection and the payment method used.