The Download Vouchers endpoint allows you to retrieve voucher details that were previously generated using a specific reference. This is typically used when:

• The voucher generation request had a quantity greater than 10 (so results were not returned immediately).
• You want to retrieve vouchers asynchronously after receiving a webhook notification.

Endpoint:

GET /api/v2/vouchers/{reference}

Path Parameter

• reference (string, required) — The unique reference you provided when generating vouchers. This ensures you retrieve the correct set.

Response

If the API endpoint is reached successfully, the HTTP status will be 200. The actual readiness of vouchers is indicated by the status field in the data object.

Fields in the Response:

• data — Contains the voucher batch details:

  • reference — Your unique request reference.

  • transactionId — Unique request identifier generated by SureGifts.

  • status — Current processing status: PROCESSING, CANCELED, or COMPLETED.

  • expiryDate — The expiration date of the vouchers.

  • value — The value loaded on each voucher.

  • vouchers — Array of voucher objects (only present when status is COMPLETED). Each object contains:

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

• statusCode — Business status code.

• message — Human-readable description of the status code.

Example Successful Response

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

Developer Notes

• Always verify status is COMPLETED before assuming vouchers are available.
• Handle PROCESSING by retrying later or waiting for a webhook notification.
• Store voucher codes and PINs securely; never expose them in logs or to unauthorized users.
• The same reference will always return the same voucher batch — useful for idempotency and reconciliation.