Gift Card Balance Inquiry

Overview

The StoredValueBalanceInquiry API call 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 other storedvalue API calls, Balance Inquiry is a synchronous call. It returns the gift card's balance available for redemption.

URI Summary

Action	URI Template	URI Example	Non-URI Request	Response
POST	/v1.0/stores/[StoreId]/payments/ storedvalue/balance/[tenderCode].[format]	/v1.0/stores/QUIK/payments/ storedvalue/balance/GS.xml	XML	200 + XML Response containing Balance Amount in the specified currency of the request

Request Format

The request is a StoredValueBalanceRequest message.

<?xml version="1.0" encoding="UTF-8"?>
<StoredValueBalanceRequest xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
  <PaymentAccountUniqueId isToken="false">4111111111111111</PaymentAccountUniqueId>
  <CurrencyCode>USD</CurrencyCode>
  <Pin>1234</Pin>
</StoredValueBalanceRequest>

Request Elements

Element	Required	Description	Type	Restriction
PaymentAccountUniqueId	No	Account ID for the gift card. This can be either a raw payment account numbe (PAN) or a token representing a PAN. The attribute isToken indicates if the PAN is tokenized.	String	Max 22 characters. Either PaymentAccountUniqueId or EncryptedPaymentAccountUniqueId is present.
EncryptedPaymentAccountUniqueId	No	Client encrypted PAN. Clients using Client Side Encryption use this element for the gift card PAN encrypted by JavaScript in the client's browser. For webstores that are not PCI compliant, this client encryption process ensures that a webstore never sees the raw PAN.	String	Max 1000 characters. Either PaymentAccountUniqueId or EncryptedPaymentAccountUniqueId is present.
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
Pin	No	PIN for the gift card	String	1 to 8 Characters. Either Pin or EncryptedPin are present.
EncryptedPin	No	Encrypted PIN for the Giftcard.	String	Up to 1000 Characters. Either Pin or EncryptedPin are present.

Request Examples

StoredValueBalanceRequest - Raw Pan

<?xml version="1.0" encoding="UTF-8"?>
<StoredValueBalanceRequest xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
  <PaymentAccountUniqueId isToken="false">4111111111111111</PaymentAccountUniqueId>
  <CurrencyCode>USD</CurrencyCode>
  <Pin>1234</Pin>
</StoredValueBalanceRequest>

StoredValueBalanceRequest - TokenizedPan

<?xml version="1.0" encoding="UTF-8"?>
<StoredValueBalanceRequest xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
  <PaymentAccountUniqueId isToken="true">4111111ak4idq1111</PaymentAccountUniqueId>
  <CurrencyCode>USD</CurrencyCode>
  <Pin>1234</Pin>
</StoredValueBalanceRequest>

Response Format

The response is a StoredValueBalanceReply message.

<?xml version="1.0" encoding="UTF-8"?>
<StoredValueBalanceReply xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
  <PaymentAccountUniqueId isToken="true">4111111ak4idq1111</PaymentAccountUniqueId>
  <ResponseCode>Success</ResponseCode>
  <BalanceAmount currencyCode="USD">50.00</BalanceAmount>
</StoredValueBalanceReply>

Response Elements

Element	Required	Description	Type	Restriction
PaymentAccountUniqueId	No	Account ID for the gift card. This can be either a raw payment account numbe (PAN) or a token representing a PAN. The attribute isToken indicates if the PAN is tokenized.	String	Max 22 characters. Either PaymentAccountUniqueId or EncryptedPaymentAccountUniqueId is present.
EncryptedPaymentAccountUniqueId	No	Client encrypted PAN. Clients using Client Side Encryption use this element for the gift card PAN encrypted by JavaScript in the client's browser. For webstores that are not PCI compliant, this client encryption process ensures that a webstore never sees the raw PAN.	String	Max 1000 characters. Either PaymentAccountUniqueId or EncryptedPaymentAccountUniqueId is present.
ResponseCode	Yes	Response Code returned from Payment Service	String	Success, Failure, 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
currencyCode	Yes	The currency used for the inquiry.	Currency code.	Currency codes are defined by ISO 4217:2008. Examples: USD, CAD, EURSee http://en.wikipedia.org/wiki/ISO_4217

Next Step

After a successful balance inquiry, a Redeem API call is the next step in the gift card checkout workflow.