Redeem voucher

post

https://staging-onlinemerchants.suregifts.com/api/v2/redeem

This endpoint redeems a voucher using the provided PIN and voucher details. The redemption amount will be deducted from the voucher balance.

Request

Method: POST
URL: /merchant-client/v2/redeem
Body: JSON object with PIN and voucher details.

Field Descriptions:

pin (string, required) – Voucher PIN.
code (string, required) – Voucher code.
amount (number, required) – Amount to redeem.

Query Parameters: None

Responses

200 OK – Successful

Field Descriptions:

data (object) – Redemption transaction details.
- transactionId (string) – Unique transaction ID.
- transactionType (string) – REDEMPTION.
- amount (decimal) – Amount redeemed.
- timestamp (datetime) – Transaction timestamp.
- reference (string) – Your external reference.
- voucherCode (string) – Masked voucher code.
- serialNumber (string) – Voucher serial number.
- refundStatus (string) – null for new redemptions.
- note (string) – null for new redemptions.
statusCode (string) – Status code ("00" indicates success).
message (string) – Human-readable message.

401 Unauthorized

Returned when authentication fails.

Unauthorized

400 Bad Request

Returned when the request is invalid (e.g., insufficient balance, invalid PIN).

Insufficient balance

Example cURL Request

curl -X POST \
  'https://{baseUrl}/merchant-client/v2/redeem' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{"pin":"1234","code":"ABC123","amount":500}'

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

The Redeem Voucher endpoint is used when a user wants to redeem a voucher either partially or fully. The request must include the voucher code, amount, and a unique reference to ensure idempotency.

Endpoint:

POST /api/v2/redeem

Request

The request body must contain:

voucherCode — The voucher code to be redeemed. This can be either a 12-digit voucher or a 16-character combination of the code and PIN. If a 16-character code is used, the pin field should be null.
pin — A 4-digit security PIN, required only if the voucher code provided is 12 digits.
amount — The amount to redeem from the voucher balance.
reference — A unique identifier for this transaction, used for reconciliation and idempotency.

Example Request:

{
  "voucherCode": "123456789012",
  "pin": "1234",
  "amount": 5000,
  "reference": "RED-2025-0001"
}

Response

When the API endpoint is reached successfully, the HTTP status will be 200. The actual outcome of the redemption is indicated by the statusCode field.

The response body contains:

data — Transaction details:
- voucherCode — The voucher code used in this transaction.
- serialNumber — Voucher’s serial number.
- transactionId — Unique transaction identifier generated by SureGifts.
- transactionType — Type of transaction, here it will be REDEMPTION.
- amount — Amount redeemed.
- timestamp — Time of redemption in ISO 8601 format.
- reference — The unique reference you supplied in the request.
statusCode — Business status code indicating success or failure.
message — Human-readable explanation of the status code.

Example Successful Response:

{
  "data": {
    "voucherCode": "123456789012",
    "serialNumber": "300002137",
    "transactionId": "789",
    "transactionType": "REDEMPTION",
    "amount": 5000,
    "timestamp": "2025-08-16T16:35:57.737Z",
    "reference": "RED-2025-0001"
  },
  "statusCode": "00",
  "message": "Successful"
}

Developer Notes

Always check statusCode to determine whether redemption succeeded.
Use a unique reference per redemption request to prevent duplicate processing.
If statusCode indicates failure, map it to user-friendly messages and handle accordingly (e.g., insufficient balance, invalid voucher, already redeemed).
Never log full voucher codes or PINs — mask sensitive data for security.

Body Params

Redemption command with PIN and voucher details

voucherCode

string

required

length between 12 and 16

[Code] is the 12-digit voucher. It can be a 16-character combination of the security PIN [Code][PIN] and the voucher code.
The pin field must be NULL if 16.

string | null

A 4 digit security PIN. Required when Voucher code is 12 digits

amount

double

required

Amount to use (required)

reference

string

required

length ≥ 1

Your special transaction reference. This will be used for transaction queries (required)

Headers

content-type

string

enum

Defaults to application/json-patch+json

Generated from available request content types

Allowed:

Response

Request

Response

Developer Notes

200OK