Gift Card Fund and Activate

Overview

The StoredValueFundAndActivate API call activates the giftcard with the specified balance. The Order Management System fulfills the order by calling the Payment Service with StoredValueFundAndActivateRequest.

This call 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 API calls, StoredValueFundAndActivateRequest is a synchronous call, 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	Non-URI Request	Response
POST	/v1.0/stores/StoreId/payments/ storedvalue/fundandactivate/ tenderCode.format	/v1.0/stores/QUIK/payments/ storedvalue/fundandactivate/ GS.xml	XML	200 + XML Response containing response status of activating and funding the gift card for the specified amount.

Request Format

The request is a StoredValueFundAndActivateRequest message.

<?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="true">411111ap49cw1111</PaymentAccountUniqueId>
  </PaymentContext>
  <Pin>1234</Pin>
  <Amount currencyCode="USD">50.00</Amount>
  <FundReason>New Giftcard</FundReason>
</StoredValueFundAndActivateRequest>

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.
Amount	Yes	Currency amount to be added to the gift card balance.	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
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 Examples

StoredValueFundAndActivateRequest - Tokenized Pan

<?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="true">411111ap49cw1111</PaymentAccountUniqueId>
  </PaymentContext>
  <Pin>1234</Pin>
  <Amount currencyCode="USD">50.00</Amount>
  <FundReason>New Giftcard</FundReason>
</StoredValueFundAndActivateRequest>

Response Format

The response is a StoredValueFundAndActivateReply message.

<?xml version="1.0" encoding="UTF-8"?>
<StoredValueFundAndActivateReply xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
  <PaymentContext>
    <OrderId>OrderId0</OrderId>
    <PaymentAccountUniqueId isToken="true">411111ap49cw1111</PaymentAccountUniqueId>
  </PaymentContext>
  <PaymentAccountUniqueId isToken="false">4111111111111111</PaymentAccountUniqueId>
  <Pin>1234</Pin>
  <ResponseCode>Success</ResponseCode>
  <Amount currencyCode="USD">50.00</Amount>
</StoredValueFundAndActivateReply>

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
Pin	No	PIN for the gift card.	String	1 to 8 Characters.
AmountFunded	Yes	Currency amount added to the gift card balance.	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