Gift Card Fund
Overview
The StoredValueFund API is used to add money to a stored value balance. Typically, this API is called when a consumer returns an order and the seller supports refunding to the gift card. The Fund API is tender-specific, and is not enabled for all stored value tenders.
Like all other storedvalue APIs, Fund 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/fund/{TenderType}.xml | /v1.0/stores/TMSUS/payments/storedvalue/fund/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. |
| 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 |
| 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 this code sample.
<?xml version="1.0" encoding="UTF-8"?>
<StoredValueFundRequest 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>
</StoredValueFundRequest>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 |
| 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
Copy this code sample.
<?xml version="1.0" encoding="UTF-8"?>
<StoredValueFundReply xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
<PaymentContext>
<OrderId>123456</OrderId>
<PaymentAccountUniqueId isToken="true">811111Ira8rU1112</PaymentAccountUniqueId>
</PaymentContext>
<ResponseCode>Success</ResponseCode>
<AmountFunded currencyCode="USD">50.00</AmountFunded>
</StoredValueFundReply>