Gift Card Fund and Activate
Overview
The StoredValueFundAndActivate API is used to activate the gift card with the specified balance. The Order Management System fulfills the order by calling the Payment Service with StoredValueFundAndActivateRequest.
This API can be used with physical or virtual gift cards. Physical gift cards are provided with account number (PAN) and PIN. Virtual gift cards are generally provided with only promo code.
Like all other storedvalue APIs, the StoredValueFundAndActivateRequest is a synchronous API, where the client is waiting for the response. In case of timeout, the webstore or Order Management System retries the transaction at a later time.
URI Summary
| Action | URI Template | URI Example | Request Content Type | Response Content Type |
|---|---|---|---|---|
| POST | /vM.m/stores/{StoreID}/payments/storedvalue/fundandactivate/{TenderType}.xml | /v1.0/stores/TMSUS/payments/storedvalue/fundandactivate/GS.xml | application/xml or text/xml | application/xml or text/xml |
Request Elements
| Element | Required | Description | Type | Restriction |
|---|---|---|---|---|
| PaymentContext | Yes - Either PaymentContext or PaymentContextBase must be present. PaymentContext is used for Physical activations where the customer has the PaymentAccountUniqueId |
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 |
| PaymentContextBase | Yes - Either PaymentContext or PaymentContextBase must be present. PaymentContextBase is used for Virtual activations where the customer does not have the PaymentAccountUniqueId |
ComplexType | ||
| PaymentContextBase/ OrderId |
Yes | Unique identifier of the order.The client must ensure uniqueness of OrderIds across all transactions that the client initiateswith this service. | String | Max 20 characters |
| Pin | No | PIN for the gift card. | String | 1 to 8 Characters. |
| Amount | Yes | Currency amount to be added to the gift card balance. | 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. |
| FundReason | No | A user readable reason for activating the gift card. | Alphanumeric | 16 characters |
| PromoCode | No | Promotion code for the activation of virtual gift cards. | String | Unlimited |
| 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 - Physical Gift Card
Copy this code sample.
<?xml version="1.0" encoding="UTF-8"?>
<StoredValueFundAndActivateRequest 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>
<FundReason>NewGiftcard</FundReason>
</StoredValueFundAndActivateRequest> Request Example - Virtual Gift Card
Copy this code sample.
<?xml version="1.0" encoding="UTF-8"?>
StoredValueFundAndActivateRequest xmlns="http://api.gsicommerce.com/schema/checkout/1.0" requestId="12345">
<PaymentContextBase>
<OrderId>123456</OrderId>
</PaymentContextBase>
<Amount currencyCode="USD">50.00</Amount>
<FundReason>NewGiftcard</FundReason>
</StoredValueFundAndActivateRequest> 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 |
| PaymentAccountUniqueId | Yes | This element returns the raw PaymentAccountUniqueId in case of Virtual activations | 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 |
| Pin | No | PIN for the gift card. | String | 1 to 8 Characters. |
| ResponseCode | Yes | Response Code returned from Payment Service. | String | Success, Fail, Timeout |
| CardClaimLink | No | Card Claim URL returned from Payment Service. | String | |
| AmountFunded | Yes | Currency amount added to the gift card balance. | Positive decimal, up to 2 decimal places | Example: 4.75 |
| AmountFunded/ @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 - Physical Gift Card
Copy this code sample.
<?xml version="1.0" encoding="UTF-8"?>
<StoredValueFundAndActivateReply xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
<PaymentContext>
<OrderId>123456</OrderId>
<PaymentAccountUniqueId isToken="true">8111111111111112</PaymentAccountUniqueId>
</PaymentContext>
<PaymentAccountUniqueId isToken="false">811111Ira8rU1112</PaymentAccountUniqueId>
<Pin>1234</Pin>
<ResponseCode>Success</ResponseCode>
<AmountFunded currencyCode="USD">50.00</AmountFunded>
</StoredValueFundAndActivateReply> Response Example - Virtual Gift Card
Copy this code sample.
<?xml version="1.0" encoding="UTF-8"?>
<StoredValueFundAndActivateReply xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
<PaymentContext>
<OrderId>123456</OrderId>
<PaymentAccountUniqueId isToken="true">810710Tv3rt1531</PaymentAccountUniqueId>
</PaymentContext>
<PaymentAccountUniqueId isToken="false">810710000001531</PaymentAccountUniqueId>
<Pin>1234</Pin>
<ResponseCode>Success</ResponseCode>
<CardClaimLink>bwus.test-claim.cards/kdEZh5XQ4k4boetmAa26aEqQ</CardClaimLink>
<AmountFunded currencyCode="USD">50.00</AmountFunded>
</StoredValueFundAndActivateReply>