Gift Card Redeem
Overview
The StoredValueRedeem API is used to deduct money from a GiftCard. It is called either by the Webstore or the Order Management System.
Like all other storedvalue APIs, Redeem is a synchronous API, where the client is waiting for the response.
If a combination of gift card(s) and credit card(s) are used for payment of an order, and any of the gift card redemption or credit card authorization operations fails, StoredValueRedeemVoid is called to void the redemption of the redeemed gift cards. The same applies for a timeout scenario on the redeem Operation as well.
For any other scenario that leads to these orders not being processed, then the webstore or order management system can either fund and activate a new card, or fund the same card back, depending on the webstore's selected preference to serve the customer.
URI Summary
| Action | URI Template | URI Example | Request Content Type | Response Content Type |
|---|---|---|---|---|
| POST | /vM.m/stores/{StoreID}/payments/storedvalue/redeem/{TenderType}.xml | /v1.0/stores/TMSUS/payments/storedvalue/redeem/GS.xml | application/xml or text/xml | application/xml or text/xml |
Request Elements
| Element | Required | Description | Type | Restriction |
|---|---|---|---|---|
| PaymentContext | Yes | Unique identifier of the payment transaction for the order | ComplexType | |
| PaymentContext/ OrderId |
Yes | Unique identifier of the order. The client must ensure uniqueness of OrderIds across all transactions that the client initiates with this service. | String | Max 20 characters |
| PaymentContext/ 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 |
| PaymentContext/ PaymentAccountUniqueId/ @isToken |
Yes (when PaymentAccountUniqueId is present) | Attribute that indicates whether the payment account number is tokenized | String | true or false |
|
PaymentContext/ |
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. |
| Amount | Yes | Currency amount to be redeemed from the gift card. | Positive decimal, up to 2 decimal places | Example: 4.75 |
| Amount/ @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. |
| requestId | Yes | RequestId is used to uniquely identify a request, including as part of idempotent duplicate request processing. The value must be unique. It is recommended to use a variant 4 UUID for the request ID. The same request ID should only be reused if a read timeout occurs when attempting to receive a response from the payment service, or the payment service responds with a fault response. In all other cases a new request ID must be sent for retried requests, including responses such as Fail, Timeout or PaymentProcessorTimeout. | String | Up to 40 Characters. |
Request Example
Copy
<?xml version="1.0" encoding="UTF-8"?>
<StoredValueRedeemRequest xmlns="http://api.gsicommerce.com/schema/checkout/1.0" requestId="12345">
<PaymentContext>
<OrderId>123456</OrderId>
<PaymentAccountUniqueId isToken="false">8111111111111112</PaymentAccountUniqueId>
</PaymentContext>
<Pin>1234</Pin>
<Amount currencyCode="USD">50.00</Amount>
</StoredValueRedeemRequest>Response Elements
| Element | Required | Description | Type | Restriction |
|---|---|---|---|---|
| PaymentContext | Yes | The PaymentContext uniquely identifies a Payment Transaction for an order. | ComplexType | |
| PaymentContext/ OrderId |
Yes | Unique identifier of the order. The client must ensure uniqueness of OrderIds across all transactions that the client initiates with this service. | String | Max 20 characters |
| PaymentContext/ PaymentAccountUniqueId |
Yes | The Payment Service Response will always return a token representing a PAN | String | Max 22 characters |
| PaymentContext/ 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 |
| AmountRedeemed | Yes | Currency amount redeemed from the gift card. | Positive decimal, up to 2 decimal places | Example: 4.75 |
| AmountRedeemed/ @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. |
| BalanceAmount | Yes | Currency amount left onthe gift card after the redemption. | 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"?>
<StoredValueRedeemReply xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
<PaymentContext>
<OrderId>123456</OrderId>
<PaymentAccountUniqueId isToken="true">811111Ira8rU1112</PaymentAccountUniqueId>
</PaymentContext>
<ResponseCode>Success</ResponseCode>
<AmountRedeemed currencyCode="USD">50.00</AmountFunded>
</StoredValueRedeemReply>Next Step
In cases where the order cannot be completed, the next step is a RedeemVoid API call.