Client APIs

# Vouchers

Vouchers are digital representations of the right to claim goods or services from a merchant. Each voucher is an instantiation of a product and inherits its characteristics.

Each voucher has two unique identifiers: the voucher code and the voucher ID.

# Voucher object

A voucher is represented as a JSON object with the following keys:

  • voucher_code: the unique voucher code (also referred to as the voucher number) that is accepted by the merchant. This code is used by the recipient and the merchant to redeem the voucher.
  • voucher_id: the unique technical reference for the voucher, used in Client API requests.
  • name: the name of the voucher as displayed to end-users, generally including its denomination.
  • status: the current status of the voucher. Possible values are active, inactive, expired, voided, and used.
  • expiration: the expiration date and time of the voucher in ISO 8601 / RFC 3339 format (opens new window) (e.g., 2030-10-12T22:59:59+00:00).
  • currency: the currency code (e.g., SGD) for the voucher's amount, or an empty string for product-based types.
  • remaining_amount: the remaining amount to spend in cents for value-based vouchers, or the number of items for product-based vouchers.
  • product_code: the product code identifying the product from which the voucher is issued.
  • product_name: the product name.
  • is_value_based: Indicates whether the voucher is value-based (true) or product-based (false).
  • is_status_available: Indicates whether the status of the voucher can be retrieved (true) or not (false) via the retrieve vouchers feature.
  • is_multiple_use: Indicates whether the vouchers can be redeemed in multiple transactions or will be fully redeemed in a single transaction.
  • url: a full URL providing direct access to the voucher, useful for embedding or redirecting to the voucher.
  • short_url optional: a shortened URL to access the voucher, used in combination with a PIN. This URL format is preferred when sharing the voucher with recipients, allowing for shorter messages such as SMS.
  • short_url_pin optional: the PIN code required to access the voucher via the short URL.
  • client_reference optional: reference provided by the client in the voucher issuance request, if any.

Important

The field list may expand with new API features. Ensure your integration can handle additional fields seamlessly.

# Example of a demo voucher object

{
  "voucher_code": "UG1123456789",
  "voucher_id": "1b5a607b-e5eb-4b17-80b0-5739c041e81b",
  "name": "$10 UNIQGIFT Value Based Test Voucher",
  "status": "active",
  "expiration": "2029-10-31T23:59:59+08:00",
  "currency": "SGD",
  "remaining_amount": 1000,
  "product_code": "MAMVDDMMYY01",
  "product_name": "$10 UNIQGIFT Value Based Test Voucher",
  "is_value_based": true,
  "is_status_available": true,
  "is_multiple_use": true,
  "url": "https://{base_url}1b5a607b-e5eb-4b17-80b0-5739c041e81b",
  "short_url": "https://{base_url_short}/v/BMhgQhHigm7",
  "short_url_pin": 1234,
  "client_reference": "CLIENT_REF_123"
}

# Accessing vouchers

For end-users, our digital vouchers are accessible through either a full or a short URL.

The full URL (url) provides direct access to the voucher without requiring additional inputs from the user.

The short URL (short_url), combined with a PIN (short_url_pin), is useful for sharing vouchers via SMS or other platforms where message length is limited. The PIN adds a layer of security, protecting against unauthorized attempts to guess the URL.

The choice between using a full URL or a short URL depends on how the vouchers are distributed to end-users. The full URL is recommended for ease of use and direct access. However, in contexts where message length matters, the short URL with a PIN is recommended.

# Short URL

The short_url and short_url_pin fields may not always be included in the response.

If your use case requires a short URL and PIN, please contact us.

← Authentication and authorization →