Gift Card Redeem

Overview

The StoredValueRedeem API call immediately deducts money from a GiftCard specified. It is called either by the webstoreor the Order Management System.

Like all other storedvalue api calls, StoredValueRedeem is a synchronous call, where the client is waiting for the response.

If multiple gift cards or a combination of gift cards and credit cards are used for payment of an order, and any of the gift card redemptions or credit card authorizations fails, StoredValueRedeemVoid is called to void the redemption of the redeemed gift cards.

URI Summary

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

Request Format

The request is a StoredValueRedeemRequest message.

<?xml version="1.0" encoding="UTF-8"?>
<StoredValueRedeemRequest xmlns="http://api.gsicommerce.com/schema/checkout/1.0"
       requestId="12345">
  <PaymentContext>
    <OrderId>OrderId0</OrderId>
    <PaymentAccountUniqueId isToken="false">4111111111111111</PaymentAccountUniqueId>
  </PaymentContext>
  <Pin>1234</Pin>
  <Amount currencyCode="USD">50.00</Amount>
</StoredValueRedeemRequest>

Request Elements

Element	Required	Description	Type	Restriction
PaymentContext	Yes	The PaymentContext uniquely identifies a Payment Transaction for an order.	ComplexType	Contains OrderId and either PaymentAccountUniqueId or EncryptedPaymentAccountUniqueId
OrderId	Yes	A unique identifier for the order. The client is responsible for ensuring uniqueness of OrderId values across all transactions the client initiates with this service.	String	20 Characters
PaymentAccountUniqueId	Yes	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
EncryptedPaymentAccountUniqueId	Yes	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
Pin	No	PIN for the gift card.	String	1 to 8 Characters. Either Pin or EncryptedPin are present.
EncryptedPin	No	Encrypted PIN for the gift card.	String	Up to 1000 Characters. Either Pin or EncryptedPin are present.
Amount	Yes	Currency amount to be redeemed from the gift card.	Positive decimal, up to 2 decimal places	Example: 4.75
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
requestId	Yes	RequestId globally identifies a request message and is used to protect against duplicate request processing.	String	Up to 40 Characters.

Request Examples

StoredValueRedeemRequest - Tokenized PAN

<?xml version="1.0" encoding="UTF-8"?>
<StoredValueRedeemRequest xmlns="http://api.gsicommerce.com/schema/checkout/1.0"
      requestId="12345">
  <PaymentContext>
    <OrderId>OrderId0</OrderId>
    <PaymentAccountUniqueId isToken="true">4111111ak4idq1111</PaymentAccountUniqueId>
  </PaymentContext>
  <Pin>1234</Pin>
  <Amount currencyCode="USD">50.00</Amount>
</StoredValueRedeemRequest>

Response Format

The response is a StoredValueRedeemReply message.

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

Response Elements

Element	Required	Description	Type	Restriction
PaymentContext	Yes	The PaymentContext uniquely identifies a Payment Transaction for an order.	ComplexType	Contains OrderId and either PaymentAccountUniqueId or EncryptedPaymentAccountUniqueId
OrderId	Yes	A unique identifier for the order. The client is responsible for ensuring uniqueness of OrderId values across all transactions the client initiates with this service.	String	20 Characters
PaymentAccountUniqueId	Yes	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
EncryptedPaymentAccountUniqueId	Yes	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
ResponseCode	Yes	Response Code returned from Payment Service.	String	Success, Failure, Timeout
AmountRedeemed	Yes	Currency amount redeemed from the gift card.	Positive decimal, up to 2 decimal places	Example: 4.75
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
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

Next Step

In cases where the order cannot be completed, the next step is a RedeemVoid API call.