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

<?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

<?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

<?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.