This is the OpenAPI specification for customer reward balance redemption APIs. These API endpoints enable customers to redeem their reward balance (as a payment method), during eCommerce checkout, as well as query their account balance. Customers do this by providing their Loyalty ID and PIN during checkout. If the provided details are correct, and the customer account is active, then the redemptions can proceed.
The endpoints are authenticated using MTLS. You will be provided with a client certificate file, and a certificate chain file, that will enable you to establish a secure connection. The implementation of this will depend on your codebase, but is a well supported and established process.
The certificate will eventually expire, and will need to be replaced. It's important not to forget this. The whoami endpoint can give you information on the expiry date on the certificate you're using, or you can inspect your client certificate yourself.
For monitoring and security, all calls to these endpoints are logged. For further troubleshooting and diagnostics, the customers Loyalty ID is the first useful item to collect and store.
The redemption endpoints use MTLS for authentication, this endpoint, allows for verification and testing of the connectivity to the platform without needing to actually create redemption actions. The endpoint will return information to confirm the correctness of the MTLS configuration. It is intended to be used during setup and developer testing.
| success required | boolean Indicates if the caller used a recognised MTLS client certificate that belongs to a Fascia |
| fascia | string The Fascia code |
| name | string The display name of the Fascia |
| message | string Any error message |
{- "success": true,
- "fascia": "EXAMPLE",
- "name": "Example Fascia"
}Take an existing authorization, and void it, returning the total redeemed balance to the customer. Use this when you want to cancel an order, for example, when the customer cancelled it, or when you cancel it due to items not in stock, or fraud detection. You cannot void a redemption that has already been captured, if so, use the refund endpoint.
Void Request Object
| token required | string (RedemptionToken) = 17 characters An alphanumeric string generated by the Loyalty platform that represents a specific redemption. You should store this with your Order payment information as you will need it to void, capture, and refund a redemptions funds. |
| success required | boolean Indicates if the void was a success |
| success required | boolean Indicates if the void was a success |
| message required | string An error message |
| success required | boolean Indicates if the void was a success |
| message required | string An error message |
{- "token": "ABC123"
}{- "success": true
}Refund a captured redemption. Used when a customer does a order return.
Refund Request Object
| token required | string (RedemptionToken) = 17 characters An alphanumeric string generated by the Loyalty platform that represents a specific redemption. You should store this with your Order payment information as you will need it to void, capture, and refund a redemptions funds. |
| amount required | number <double> >= 0.01 The refund value, any amount above zero up until and including the total authorized in the original redemption., 12.34 |
| orderId | string |
| success required | boolean Indicates if the refund was a success |
| message | string If there was an error, an error message |
| success required | boolean Indicates if the void was a success |
| message required | string An error message |
| success required | boolean Indicates if the refund was a success |
| message required | string An error message |
{- "token": "8WBaER9JMiPiJFCs3",
- "amount": 12.34
}{- "success": true
}During checkout, the customer provides their Loyalty ID and their PIN. This is used on the lookup endpoint to verify the customer exists, the PIN is correct, the customer is in a valid state to perform redemptions, and if successful, will reveal the customers available rewards balance. Any calls to authorize a redemption will fail if the requested value is greater than the customers available balance.
Note that all operations will return 'Customer Not Found' in instances when the PIN is incorrect, or the customer account is in a deactivated state.
Loyalty ID and PIN to verify, provided by customer during checkout.
| loyaltyId required | string (LoyaltyId) = 10 characters ^([A-Z0-9]{10,16})$ The customer Loyalty ID, alphanumeric, uppercase. In a customer facing context, this might be refererd to as their 'Reward Code'. |
| pin required | string (CustomerPIN) = 4 characters ^(\d{4})$ The customer PIN is provided and required to authorize redemptions. If the PIN is incorrect, the customer will simply present as 'not found'. It is 4 digits sent as a string. |
| customerIpAddress | string (CustomerIPAddress) The end user IP address which originally requested the redemption. Used for fraud detection and monitoring. Can be IPv4 or IPv6. |
| customerUserAgent | string (CustomerUserAgent) The end user browser User Agent which originally requested the redemption. Used for fraud detection and monitoring. |
| success required | boolean Indicates if the lookup revealed a valid customer |
| loyaltyId | string (LoyaltyId) = 10 characters ^([A-Z0-9]{10,16})$ The customer Loyalty ID, alphanumeric, uppercase. In a customer facing context, this might be refererd to as their 'Reward Code'. |
| currency | string The reward balance currency |
| balance | number <double> The reward balance |
| message | string Any error message |
| success required | boolean Indicates if the refund was a success |
| message required | string An error message |
{- "loyaltyId": "XK1VL83QW2Y",
- "pin": "1234",
- "customerIpAddress": "01.102.103.104",
- "customerUserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/132.0.0.0 Safari/537.36"
}{- "success": true,
- "loyaltyId": "XK1VL83QW2Y",
- "currency": "GBP",
- "balance": 1234.56
}Capture a redemption. Used for eCommerce sales which are authorized during checkout and captured during warehouse fullfilment.
Capture Request Object
| token required | string (RedemptionToken) = 17 characters An alphanumeric string generated by the Loyalty platform that represents a specific redemption. You should store this with your Order payment information as you will need it to void, capture, and refund a redemptions funds. |
| amount required | number <double> >= 0.01 The redemption value, any amount above zero up until and including the total authorized in the original redemption., 12.34 |
| partial | boolean Indicate if this is going to be a partial capture, i.e. not using the full available authorized balance. |
| success required | boolean Indicates if the capture was a success |
| message | string If there was an error, an error message |
| retryPossible | boolean If the client can make the request again (i.e. in temporary errors) |
| success required | boolean Indicates if the void was a success |
| message required | string An error message |
| success required | boolean Indicates if the capture was a success |
| message required | string An error message |
{- "token": "8WBaER9JMiPiJFCs3",
- "amount": 12.34
}{- "success": true
}Authorize a new redemption, consuming the customer balance. Used for eCommerce sales which are authorized during checkout, and captured during warehouse fullfilment.
Authorize Request Object
| loyaltyId required | string (LoyaltyId) = 10 characters ^([A-Z0-9]{10,16})$ The customer Loyalty ID, alphanumeric, uppercase. In a customer facing context, this might be refererd to as their 'Reward Code'. |
| currency required | string = 3 characters Currency |
| amount required | number <double> >= 0.01 The value you want to redeem, any amount above zero up until and including the total available rewards balance in the customers account. The value requested should be less than your order total. Over-redemptions will be voided during reconciliation. |
| pin required | string (CustomerPIN) = 4 characters ^(\d{4})$ The customer PIN is provided and required to authorize redemptions. If the PIN is incorrect, the customer will simply present as 'not found'. It is 4 digits sent as a string. |
| orderId required | string The new Order ID, this should be the same as the Order ID presented for reconciliation. |
| customerIpAddress | string (CustomerIPAddress) The end user IP address which originally requested the redemption. Used for fraud detection and monitoring. Can be IPv4 or IPv6. |
| customerUserAgent | string (CustomerUserAgent) The end user browser User Agent which originally requested the redemption. Used for fraud detection and monitoring. |
| success required | boolean Indicates if the redemption was a success |
| message | string If there was an error, an error message |
| updatedBalance | number <double> The new customer balance |
| token | string (RedemptionToken) = 17 characters An alphanumeric string generated by the Loyalty platform that represents a specific redemption. You should store this with your Order payment information as you will need it to void, capture, and refund a redemptions funds. |
| success required | boolean Indicates if the void was a success |
| message required | string An error message |
| success required | boolean Indicates if the authorization was a success |
| message required | string An error message |
{- "loyaltyId": "XK1VL83QW2Y",
- "currency": "GBP",
- "amount": 10,
- "pin": "1234",
- "orderId": "EXAMPLE_ORDER_ID",
- "customerIpAddress": "01.102.103.104",
- "customerUserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/132.0.0.0 Safari/537.36"
}{- "success": true,
- "updatedBalance": 30,
- "token": "8WBaER9JMiPiJFCs3"
}