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 this code sample.
<?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 this code sample.
<?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 this code sample.
<?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.