Merchant APIs

# Redeem Voucher

This is the API call to redeem a voucher for a purchase in a shop. It requires an active voucher with sufficient remaining value for the transaction.

This is step ❷ after checking the voucher status.

In the API backend, two transaction events are generated for this call: one for the authorization and one for the capture. The capture transaction confirms the successful redemption of the voucher.

# Needed Voucher Information

This information is used in the request body.

  • currency: the currency of the redeem transaction to capture for value-based products.
  • value: the amount to capture in cents in the transaction currency for value-based products.
  • product_class: reference to the catalogue of products. For our DEMO and UAT environments, the value for this parameter is ETX_001.
  • ref: unique reference displayed on the voucher. Also available on the voucher as a QR or bar code depending on the its design.

# Other Request Parameters

  • X-Client-Id and X-Client-Secret: credentials of the shop interacting with the API, see also Authentication.
  • return_vouchers_info: see below.

# Return Vouchers Information

The optional query parameter return_vouchers_info can be added in the request to display voucher information in the response (to be used in a display screen for instance).

By default, this parameter is set to false.

The format for this parameter in the query string is ?return_vouchers_info={boolean}.

# Main Information Returned

  • status: confirming that the redemption is successful. Invalid redeem requests are returned with error codes like 400 Bad Request.
  • capture_id: the ID of the capture transaction confirming the redemption that is required for Refunding a voucher.

A successful redeem action updates the remaining value and the voucher status accordingly.

# Other Available Information

  • mid: the merchant ID
  • authorization_id: an internal transaction ID corresponding to the redeem request.
  • authorized_amount: authorized amount to be captured on the voucher.
  • captured_amount: confirmation of the amount captured on the voucher.
  • vouchers: details of the voucher if return_vouchers_info=true was requested.
  • links: a list of API links of available actions after this API call. In this request the links to the refund transaction.

# Example of an API Call

# API Endpoint and Headers

POST https://api.merchant.demo.uniqrewards.com/v1/transactions?return_vouchers_info=false

Headers:
X-Client-Id: a1f64ebc9c4fef739df58f5933ceec94
X-Client-Secret: 1231f6112bbff1b03892306f53281bb0
Content-Type: application/json

The return_vouchers_info parameter is optional and false by default.

# Request Body

{
    "currency" : "SGD",
    "vouchers": [
        {
            "value": 200, 
            "product_class": "ETX_001",
            "ref": "1701221318"
        }
    ]
}

# Response Body

{
  "data": {
    "authorization_id": "0000100000000000017120211228002795713",
    "capture_id": "0000100000000000017120211228002795714",
    "mid": "000000000000171",
    "captured_amount": 200,
    "authorized_amount": 200
  },
  "meta": {
    "status": "succeeded"
  },
  "links": [
    {
      "rel": "refund",
      "href": "/api/transactions/edr-0000100000000000017120211228002795714/actions/refund"
    }
  ]
}

Note: the sample values in this page are mock-up values. They are not valid credentials and they are not associated to any actual product or voucher.

More details can be found on the Technical Documentation (opens new window).

← Refund a Voucher →