Claiming a Reward

Last updated: September 23rd, 2019

Claiming a Reward

Once you have created an order and instruction, you can then claim the reward.

Access Requirements

You will need a Tenant API Key to process a reward.

For more information on creating a Access Token, see:

Functions

The available functions are:

  1. Claim a Reward
  2. Get the reward

API Documentation

All the Payment Order API functions are fully documented in the Transaction API documentation.

Models

The following model is returned when the Get a Reward endpoint is called.

Claim Status Model

{
  "status": "string",
  "data": {
    "credentialList": [
      {
        "label": "string",
        "value": "string",
        "rewardType": "string",
        "credentialType": "string"
      }
    ],
    "redemptionInstructions": "string"
  }
}
Property Type Description
status string The status of the claim. Possible values are SETTLING (default), SETTLED, and FAILED.
data Reward Claim Model object Value is null until the status is SETTLED.

Reward Claim Model

Property Type Description
credentialList array of Credential Models An array of Credential models

Can help you present the credentials to your customer.
redemptionInstructions decimal The redemption instructions to present to your customer.

Credential Model

{
  "label": "string",
  "value": "string",
  "rewardType": "string",
  "credentialType": "string"
}
Property Type Description
label string A friendly string that you can use to label the value property in a UI.

For example, if the reward was an Amazon gift card
then the label might be Amazon Gift Card claim code.
value string The value of the credentials.

For example, if label was Amazon Gift Card claim code
then the value would be the claims code for the reward
ie. S5WQ-Z2SP5S-GLB3.
rewardType string See Reward Types below.
credentialType string Use the Credential Types to determine the best format for your UI.

See Credential Types below.

Reward Types

We return the following types of reward credentials. If your integration requires displaying reward data in app or creating custom reward emails you may need to add logic to parse the returned reward data correctly.

Note - we are continuously expanding our catalog and it is likely that new reward types will arise over time. For this reason we recommend a fallback / default to handle unspecified types as text.

Reward Type Description Integration Example
text Plain Text Wrap in a <span> tag.
url URL to a reward landing page Wrap in a <a> tag.
barcode URL for a barcode image Add an <img> tag.
date ISO datetime Display in localized date format based on locale of reward according to RFC 3339, i.e. 2016-01-01T00:00:00Z.

Credential Types

Credential Types specify the type(s) of data that a reward will give you. Common ones are cardNumber and expirationDate but any from the following list can be found in rewards.

Credential Type Description
barcodeNumber A numeric or alphanumeric string that provides a human readable version
of the information embedded in a barcode.
This is typically used in conjunction with the barcodeUrl credential.
barcodeUrl A URL for a barcode image.
This is typically used in conjunction with the barcodeNumber credential.
bypassUrl A landing page URL that includes secondary credential information.
This removes the need for the recipient to input
secondary credentials on the landing page.
cardCode A numeric or alphanumeric string.
cardNumber A numeric or alphanumeric string.
cvc2 A 3-digit numeric code used as a secondary credential for financial products.
eventNumber A secondary credential that is numeric or alphanumeric string.
expirationDate A date after which the issued reward will no longer be redeemable.
pin Personal Identification Number. A secondary credential that is a numeric or alphanumeric string.
redemptionUrl A landing page URL where reward credentials and redemption information are
typically presented.
The landing page may or may not require the recipient to enter one or more
secondary credentials to complete the reward redemption process.
secretCode A secondary credential that is numeric or alphanumeric string.

Steps to Claim a Reward

The act of claiming a reward ensures the reward is paid for and ready for redemption. The redeem response will include the appropriate details needed to allow your customer to redeem their selected reward with the reward provider, ie. Amazon, etc.

The process to claim a reward is a 2 step procedure.

  1. Claim a Reward
  2. Get the Reward

Step 1 - Claim a Reward

Call the /v1/order-management/{orderRef}/instruction/{instructionRef}/claim-reward endpoint to immediately receive a link to a TransactionId in the response headers.

The time taken to claim a reward can vary so we give you a TransactionId to check against while we process the claim in the background.

Step 2 - Get the Reward

Call the /v1/customer-vault/{customerRef}/reward/{financialInstrumentId}/transaction/{transactionId} endpoint, replacing {transactionId} with the actual Transaction Id from Step 1.

Check the status property. If the status is still SETTLING we need to repeat Step 2. We would recommend polling every second until the status changes from SETTLING.

Note: There will be variances in processing times depending on your rewards provider.

When the status changes to either SETTLED or FAILED the transaction is complete.

When the status is SETTLED, the data property will contain a Reward Claim Model.

Use the credential list items to help you render a UI for your customer together with the redemptionInstructions, which instruct your customer on how to redeem the reward.