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/ EncryptedPaymentAccount UniqueId	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

<?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

<?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>