The Generate Vouchers endpoint allows you to request the creation of one or more vouchers. Depending on the quantity and configuration, vouchers can be delivered immediately or made available later via a webhook or a separate download call.

Endpoint:

POST /api/v2/vouchers

Request

The request body accepts the following parameters:

• quantity (int32, required) — The number of vouchers to produce. For immediate retrieval in the response, this must be ≤ 10. Larger quantities will be delivered via webhook or can be downloaded later using the same reference.
• reference (string, required) — Your unique request identifier. This will be used for downloading vouchers later and ensures idempotency.
• value (double, optional) — The value to load on each voucher. If greater than zero, vouchers are activated immediately. If null, activation will be delayed until triggered in-store.
• expiryDate (date-time, optional) — Expiration date for the vouchers. Must be at least one day after the request date. If omitted, the expiry defaults to 365 days from the current date.

Example Request:

{
  "quantity": 5,
  "reference": "VCH-2025-0001",
  "value": 5000,
  "expiryDate": "2025-08-20T17:43:51.925Z"
}

Response

When the endpoint is reached successfully, the HTTP status will be 200. The business outcome is determined by statusCode.

Fields in the Response:

• data — Main payload containing:

  • reference — The same reference you sent in the request.

  • transactionId — Unique request ID generated by SureGifts.

  • status — Current request status. Can be PROCESSING, CANCELED, or COMPLETED.

  • expiryDate — Expiration date of the vouchers.

  • value — Value per voucher.

  • vouchers — Returned only when status is COMPLETED. Each voucher object includes:

    • serialNumber — Voucher serial number.
    • code — Voucher code.
    • pin — Voucher PIN (if applicable).

• statusCode — Business status code.

• message — Description of the statusCode.

Example Successful Response:

{
  "data": {
    "reference": "VCH-2025-0001",
    "transactionId": "12345",
    "status": "COMPLETED",
    "expiryDate": "2025-08-20T17:43:51.925Z",
    "value": 5000,
    "vouchers": [
      {
        "serialNumber": 300002137,
        "code": "ABC123XYZ",
        "pin": "7890"
      }
    ]
  },
  "statusCode": "00",
  "message": "Successful"
}

Developer Notes

• For large quantity values (> 10), implement webhook handling or use the reference to query/download vouchers later.
• Always check statusCode and status before assuming vouchers are ready.
• Store voucher details securely. Never expose full codes or PINs in logs or to unauthorized parties.