This endpoint allows you to check the current balance and usable amount of a voucher. It also returns the voucher’s transaction history, covering both activation and redemption events.

Endpoint

POST /api/v2/balance

Request Body

• voucherCode (string, required, length 12–16)
  The voucher code to be validated.

  • If the voucher code is 12 digits, you must provide the pin.
  • If the voucher code is 16 digits (concatenation of code + pin), the pin field must be null.

• pin (string, optional)
  A 4-digit security PIN. Required only when the voucher code is 12 digits.

Sample Request

{
  "voucherCode": "123456789012",
  "pin": "1234"
}

Response

• data.serialNumber (number) → Unique voucher serial number.

• data.voucherCode (string) → The voucher code queried.

• data.balance (number) → Current voucher balance.

• data.usableAmount (number) → Redeemable balance after deductions.

• data.transactions (array) → List of past voucher transactions. Each transaction includes:

  • transactionId (string) → Unique SureGifts transaction ID.
  • transactionType (string) → Type of transaction (ACTIVATION or REDEMPTION).
  • amount (number) → Amount transacted.
  • timestamp (datetime) → Date and time of transaction.
  • reference (string) → Merchant reference used for the transaction.

• statusCode (string) → Business rule outcome code. Always returned even if HTTP status is 200.

• message (string) → Human-readable explanation of the statusCode.

Sample Response

{
  "data": {
    "serialNumber": 987654321,
    "voucherCode": "123456789012",
    "balance": 5000,
    "usableAmount": 4500,
    "transactions": [
      {
        "transactionId": "TXN-001",
        "transactionType": "ACTIVATION",
        "amount": 5000,
        "timestamp": "2025-08-16T16:38:42.834Z",
        "reference": "REF-001"
      },
      {
        "transactionId": "TXN-002",
        "transactionType": "REDEMPTION",
        "amount": 500,
        "timestamp": "2025-08-16T17:10:10.000Z",
        "reference": "REF-002"
      }
    ]
  },
  "statusCode": "00",
  "message": "Balance retrieved successfully"
}