Client APIs

# Request Vouchers

Version

This page is for the Client API v2. For the Client API v3 documentation, please see the issue vouchers page.

This API call generates e-vouchers on demand. The e-vouchers returned in the API response can then be sent to the voucher recipients.

# Authentication and Authorization

See our page on Authentication and Authorization.

# Needed Information

In order to make a successful call, you need to send several information in the API call.

# Catalogue of Products

The main source of parameters for voucher issuance is the catalogue of products.

It consist in a list of products identified by a code (product_code). Each product code is associated with an order number (order_number) and a product type (product-based, fixed value-based, dynamic value-based, etc.).

The catalogue of products will be provided together with the API credentials, usually as a file.

See as well the integration process page for the pre-requisites to obtain the catalogues.

Catalogue example
Product Name Product Code Order Number Product Type
$10 UNIQGIFT Value Based Test Voucher MAMVDDMMYY01 202112172914 fixed value-based
$50 UNIQGIFT eGift Card SUV050ECARD03 202201132944 convertible
${FV} UNIQGIFT Groceries Voucher UNIVGROCERIESDYNAMIC01 202208013226 dynamic value-based

# Request Parameters

The API request requires the following information:

  • product_class: This is a reference to the class of products to issue vouchers from. The value for this parameter is ETX_001 for all requests and all environments.
  • order_number: To generate the invoice associated to an API request call, we use the order number from the catalogue of products.
  • product_code: The code that identifies the product to issue the vouchers. See as well the catalogue of products.
  • manual_quantity: The number of vouchers to be issued. Limited at 20 per request.
  • face_value (Optional): For dynamic value-based vouchers only. This is the expected face value to issue in SGD and can be any amount between 1 and 1000 ($1 to $1000). Please refer to Dynamic products issuance for more information.

Tip

To work around the limitation on manual_quantity, clients may issue more than 20 vouchers using several voucher issuance requests.

# Idempotency

That API endpoint enforces idempotency which is the ability to generate the same response to several requests using the same idempotency ID.

  • X-Correlation-Id: The idempotency ID for your API call. The expected format is UUID.

This allows us to properly handle issues such as network timeouts when there is a connection problem in the middle of an API call. If the API's client sends a request to the server but does not receive a response, the API client can safely reiterate its request with the same idempotency ID:

  • If the server has NOT received this ID during the interrupted call, then we will treat the API call as a new API request.
  • If the server HAS already received this ID during the interrupted call, then the server response to the client will be identical to the response previously sent but not yet received by the API client.

This capability allows us to avoid issuing vouchers more than once when there was an issue with a previous call.

Please also refer to the page Issue recovery using idempotency on how to implement a recovery process.

# Returned Voucher Details

For each successful API call, we will return the following information:

  • voucher_ref: A reference to the voucher.
  • voucher_settlement_ref: The unique reference to the voucher in UUID format.
    • This is used as a parameter in the API request to get the status of the voucher.
    • This also can be used to generate a unique URL to access the voucher: https://s.ticketxpress.sg/viewvoucher.aspx?voucherguid={voucher_settlement_ref} for the DEMO or UAT environments.
  • voucher_name: The name of the product.
  • status: The status of the voucher. The status for a newly generated voucher is Active.
  • expiration_date: The expiration date for this voucher.
  • edenred_url: a short URL to access the voucher, this can be used as a replacement for the long URL to the voucher but MUST be used in combination with the view_code for security reason (short URLs are susceptible to brute force attacks).
  • view_code: The PIN code needed to access the short URL.
  • display_codes: Used if a display code is to be displayed on the voucher. Empty for the sample response.

# Example of an API Call

# API Endpoint

POST https://api.demo.uniqrewards.com/v2/catalogs/{product_class}/product_assets/{order_number}/products/{product_code}/vouchers/actions/request

# Request Headers

X-Client-Id: a1f64ebc9c4fef739df58f5933ceec94
X-Client-Secret: 1231f6112bbff1b03892306f53281bb0
X-Correlation-Id: f6dc536c-82fe-bccb-8639-9cb85a4eefcd
Authorization: Bearer 
77F309C43E153B286FE6BB1FBB2A901C15DDA9F619E82B4522EDE988B8C409CF
Content-Type: application/json

# Request Body

{
  "manual_quantity": 1,
  "distribution_mode": "manual"
}
  • manual_quantity: the quantity of vouchers requested, 1 or more.
  • distribution_mode: manual for this example. The voucher details will be provided in the API response and the distribution to the voucher recipient is to be done by the client.

# Response

HTTP/1.1 200 OK

Content-Type: application/json; charset=UTF-8

{
  "meta": {
    "status": "succeeded"
  },
  "data": [
    {
      "voucher_ref": "30V45P1D",
      "voucher_settlement_ref": "ce7abcca-17ad-c30d-271f-423b33a01145",
      "voucher_name": "$5 Sample Voucher",
      "status": "Active",
      "expiration_date": "2029-12-31T23:59:59",
      "edenred_url": "https://s.ticketxpress.sg/v/oBy6COpxHg",
      "view_code": "3058",
      "display_codes": [
        
      ]
    }
  ]
}

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, order or voucher.

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

← Check Vouchers →