Gift Card Balance Inquiry
Overview
The StoredValueBalanceInquiry API is used to view or confirm funds on a specific gift card. Both the webstore and Order Management System make this API call at various phases of order processing.
Like all other storedvalue APIs, Balance Inquiry is a synchronous API, where the client is waiting for the response. It returns the gift card's balance available for redemption.
Recaptcha must be implemented by the system that does a balance inquiry call.
The optionality of PIN in the request depends on the store's configuration by the Gift Card provider.
URI Summary
| Action | URI Template | URI Example | Request Content Type | Response Content Type |
|---|---|---|---|---|
| POST | /vM.m/stores/{StoreID}/payments/storedvalue/balance/{TenderType}.xml | /v1.0/stores/TMSUS/payments/storedvalue/balance/GS.xml | application/xml or text/xml | application/xml or text/xml |
Request Elements
| Element | Required | Description | Type | Restriction |
|---|---|---|---|---|
| PaymentAccountUniqueId | Yes - Either PaymentAccountUniqueId or EncryptedPaymentAccountUniqueId must be present. |
Either a raw PAN (payment account number such as a credit card number) or a token representing a PAN | String | Max 22 characters |
| PaymentAccountUniqueId/ @isToken |
Yes (when PaymentAccountUniqueId is present) | Attribute that indicates whether the payment account number is tokenized | String | true or false |
| EncryptedPaymentAccountUniqueId | Yes - Either PaymentAccountUniqueId or EncryptedPaymentAccountUniqueId must be present. |
Client-encrypted PAN. Used for clients who use client-side encryption to encrypt credit card numbers in the JavaScript that runs in their browser. For a webstore that is not PCI compliant, this ensures that the webstore never sees raw PANs. | String | Max 1000 characters |
| Pin | No | PIN for the gift card | String | 1 to 8 Characters. Either Pin or EncryptedPin can be used. |
| EncryptedPin | No | Encrypted PIN for the Giftcard. | String | Up to 1000 Characters. Either Pin or EncryptedPin can be used. |
| CurrencyCode | Yes | The currency used for the transaction. | Currency code | Currency codes are defined by ISO 4217:2008. Examples: USD, CAD, EURSee http://en.wikipedia.org/wiki/ISO_4217 |
Request Example - Raw Pan
Copy
<?xml version="1.0" encoding="UTF-8"?>
<StoredValueBalanceRequest xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
<PaymentAccountUniqueId isToken="false">8111111111111112</PaymentAccountUniqueId>
<Pin>1234</Pin>
<CurrencyCode>USD</CurrencyCode>
</StoredValueBalanceRequest>Request Example - TokenizedPan
Copy
<?xml version="1.0" encoding="UTF-8"?>
<StoredValueBalanceRequest xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
<PaymentAccountUniqueId isToken="true">811111Ira8rU1112</PaymentAccountUniqueId>
<Pin>1234</Pin>
<CurrencyCode>USD</CurrencyCode>
</StoredValueBalanceRequest>Response Elements
| Element | Required | Description | Type | Restriction |
|---|---|---|---|---|
| PaymentAccountUniqueId | Yes | The Payment Service Response will always return a token representing a PAN | String | Max 22 characters |
| PaymentAccountUniqueId/ @isToken |
Yes (when PaymentAccountUniqueId is present) | Attribute that indicates whether the payment account number is tokenized | String | In the the Response object this element will always be true |
| ResponseCode | Yes | Response Code returned from Payment Service. | String | Success, Fail, Timeout |
| BalanceAmount | Yes | The amount left on the gift card in the specified currency with currencyCode as an attribute |
Positive decimal, up to 2 decimal places |
Example: 4.75 |
| BalanceAmount/ @currencyCode |
Yes | Type of currency used for the order | String | 3-character ISO 4217 code (for example, USD, CAD, EUR). See
http://en.wikipedia.org/ wiki/ISO_4217. |
Response Example
Copy
<?xml version="1.0" encoding="UTF-8"?>
<StoredValueBalanceReply xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
<PaymentAccountUniqueId isToken="true">811111Ira8rU1112</PaymentAccountUniqueId>
<ResponseCode>Success</ResponseCode>
<BalanceAmount currencyCode="USD">940.46</BalanceAmount>
</StoredValueBalanceReply> Next Step
After a successful balance inquiry, a Redeem API call is the next step in the gift card checkout workflow.