Workflow Overview

The redemption workflow consists of 2 primary calls:

• A first to validate the gift is found, is valid for redemption at the specified location and at the current time, and check its available balance.
• A second call to execute the redemption using a specified amount.
• Non-promotional gifts generally do not expire and have no usage restrictions. Promotional gifts however do expire, may have future validity periods, have restrictions on which items they can apply to (for item based gifts), and may have other terms that could be validated by a cashier. To avoid awkward UX - after validation - restriction / eligibility related fields can be checked.
• Gifts can be multi-use and can be redeemed partially until depleted. This applies to both monetary and item-based gifts.
• Lastly, if a Gift Redemption needs to be reversed - this is available via the reversal API.

For guidance on how we have visualized this workflow, see our:

Merchant Redemption App UI Reference.

1. Validate Gift

Verify a gift is valid and usable at the redemption location and retrieve gift information including current balance or eligible items.

1. Expected inputs
   1. Authentication Token (as HTTP header; provides identity and account)
   2. Location Identifier (could possibly be encoded in the Authentication Token)
   3. For Manual Entry: The 12 digit numeric voucher code
   4. For QR Entry: The voucher card public token
   5. For POS Redemption: POS ticket data (optional)
   6. Validation Options (optional)
2. Expected Outputs
   1. Successful response if gift is usable at location
   2. Gift data
      1. Type: Monetary or Item Gift
      2. Remaining Value or Gift Label and Quantity
      3. Sender / Recipient Info
      4. Indicators if the gift has remaining balance, is in a redeemable status, and in redeemable period.

In important note: the Validate API will return success as long as the gift exists and is valid for the calling merchant - even if it’s not currently redeemable (i.e. its already redeemed, expired, etc.). It is important to verify the state of the gift by checking if voucher.isRedeemable is true before calling redeem.

Additionally voucherEligibleValue or voucherEligibleItemQuantity will be > 0 if a gift is redeemable - and will indicate if the gift is momentary or item-based (as eligible value will be specified for monetary, eligible item quantity for item gifts). voucherPresentValueDescription can be used as a display field to cashiers or consumers that encapsulates both the balance and status in a single message (it shows the balance if redeemable but an explanation if not).

2. Redeem Gift

Decrement the current balance of the gift. This should be called when a check is closed / payment processed.

Unlike the Validate API, if the gift is not currently redeemable, this API will return an error.

1. Expected inputs
   1. Authentication Token (as HTTP header; provides identity and account)
   2. Location Identifier (could possibly be encoded in the Authentication Token)
   3. Voucher Identifier
   4. Redemption Amount
   5. Validation Options (optional)
2. Expected Outputs
   1. Successful if redemption applied
   2. Gift data
      1. Including update Remaining Balance or Quantity
   3. Redemption transaction identifier

3. Reverse Redemption

Reverse a prior redemption and restore the value to the gift.

1. Expected inputs
   1. Authentication Token (as HTTP header; provides identity and account)
   2. Location Identifier (could possibly be encoded in the Authentication Token)
   3. Redemption transaction identifier (from prior redemption operation)
2. Expected Outputs
   1. Successful if value restored
   2. Redemption transaction record data
      1. Shows redemption and reversal state data

POS Redemption Process

If you are implementing an on premise POS-redemption process, the steps described above looks like the following in practice:

Non-Promotional (C2C)

For consumer-to-consumer gifts (ie "gift cards"):

Promotional (B2C)

For business-to-consumer promotional gifts (ie vouchers or coupons):