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/
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
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 globally identifies a request message and is used to protect against duplicate request processing. String Up to 40 Characters.

Request Example - Physical Gift Card

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

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

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

<?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>
    <AmountFunded currencyCode="USD">50.00</AmountFunded>
</StoredValueFundAndActivateReply>