Gift Card Processing

A gift card is a prepaid card that carries a currency amount determined at the time of the card's purchase. Gift cards are often referred to as stored value cards.

There are two main categories of gift cards: Physical Gift Cards and Virtual Gift Cards.

  • With a Physical Gift Card purchase, a consumer receives as an actual card that can be redeemed at a store location or online.
  • A Virtual Gift Card can only be purchased online and does not have a physical card associated with the purchase.

Most of the gift card API calls are identical for physical and virtual gift cards. An exception is the FundAndActivate call, which returns different data for the two types of gift cards.

All the storedvalue API calls are synchronous calls, where the client is waiting for a response. In case of timeout, the webstore or Order Management System retries the transaction at a later time.

If multiple gift cards or a combination of gift cards and credit cards are used for payment of an order, and any of the gift card redemptions or credit card authorizations fails, StoredValueRedeemVoid is called to void the redemption of the redeemed gift cards.

Gift Card Activation Flow

For virtual gift cards, the are two ways a card can be activated.

  • Card-based activation which returns the card number and PIN. This is the default behaviour.
  • URL-based activation which returns the URL link (CardClaimLink) where the customer can claim the card themselves. The webstore or OMS must work with Radial's technical team to discuss the possibility of using a CardClaimLink.
  1. Either the webstore or Order Management System initiates the FundAndActivate API call to activate and fund the gift card (either physical or virtual) for the specified currency amount.
    • Physical gift cards activations require the gift card number (also known as PAN), the PIN, and the amount to be loaded on the gift card.
    • Some gift card providers may require a promocode and the amount to be loaded on the gift card.
  2. The FundAndActivate call returns with response status, and/or the gift card number for virtual gift cards.
    1. By default, the response will have the gift card number and PIN.
    2. If the Store is configured for activation through URL, the CardClaimLink which contains the URL to claim the card will be sent in the reply. The gift card number returned will not be the actual card number but a proxy number. There will be no PIN present in this case.
      • If the ResponseCode received is "Timeout", the same request should be called again with different RequestId.
  3. The webstore or Order Management System returns the status and gift card number and PIN to the customer(for virtual cards).

Flow Diagram: Gift Card Activation

Gift Card Checkout Flow

The flow diagram below covers all of the system interactions that occur between a Webstore, an Order Management System (OMS) and the Payments API. The Risk API is assumed to return success in all of the scenarios shown.

  1. Either the webstore or Order Management System makes the Redeem API call to deduct funds from the gift cards for the order placed.
  2. BalanceInquiry call is made after the Redeem to confirm that the funds were deducted.
  3. Failure events are handled as follows:
    • If the Risk service returns failure, a RedeemVoid API call is made to void the payments initially made by the Redeem request.
    • If multiple gift cards or a combination of gift cards and credit cards are used for payment of an order, and any of the gift card redemptions or credit card authorizations fails, the webstore or Order Management System calls a RedeemVoid to void the payments initially made by the Redeem request.
    • In case of a timeout or failed redemption on any gift card, the webstore or Order Management System follows up with RedeemVoid to void any previous redemption on the giftcard.

Flow Diagram: Gift Card Checkout

Canceled Order

Flow Diagram: Gift Card Order Canceled Because of Fraud Risk Assessment

Flow Diagram: Order Canceled, Giftcard Redemption Failure When Using Multiple Giftcards

Flow Diagram: Order Canceled, Credit Card Authorization Failure When Using Multiple Tenders

Gift Card Order Return Flow

This flow covers all of the system interactions that occur between a webstore, the Order Management System (OMS), and the Payments API. In case of Order Return or Order Cancel, for an order where gift card is a tender, seller-specific rules determine the API call to be made.

  1. The Order Management System makes the CashOut API call to deactivate the gift card and the FundAndActivate API call to issue a new gift card. The API calls made as part of order return are seller-specific.
  2. The Order Management System makes the Fund API call to load funds to the new gift card for the order returned. The customer returns the order, and the Order Management System loads the currency amount as specified in the request. The API calls made as part of the order return process are seller-specific.
  3. In case of a timeout or failed funding on any gift card, the Order Management System retries at a later time.

Flow Diagram: Order Return, Fund the Gift Card

Flow Diagram: Order Return, Issue a New Gift Card)

Gift Card Cancellation Flow

This flow covers all of the system interactions that occur between a webstore , the Order Management System (OMS), and the Payments API. This flow is triggered by Order Return or Order Cancel for a gift card (not necessarily paid by a gift card).

  1. When the customer decides to return a physical gift card or cancel a virtual gift card, the CashOut API call is made to devalue and deactivate the card.
  2. In case of a timeout or failed cashout on any gift card, the Order Management System retries at a later time.

Flow Diagram: GiftCard Cancellation