Redeem Voucher

This endpoint allows you to redeem a voucher against an eligible redemption product. Use /redeem whenever your customer is presenting a voucher PIN for consumption, and /purchase whenever you are buying a new product (airtime, data, electricity, etc.).

Path: POST /redeem

Authentication Required:

---

Who Can Call This Endpoint

Only users at the Merchant or Sub-Merchant level can call /redeem. Partner and Vendor users will receive 403 Forbidden. See Access & Permissions.

Product Eligibility

You can only redeem products that are active under your merchant account. Attempts to redeem any other product return responseCode: "1009". See Product Availability.

Use the product catalog endpoints to discover which redemption products are available to you.

---

Headers

Authorization: Bearer <YOUR_BEARER_TOKEN>
Content-Type: application/json

---

Request Body

{
  "productCode": "OTT-REDEEM-001",
  "amount": 10.00,
  "voucherPin": "1234567890",
  "mobileNumber": "821234567",
  "paymentMethod": "cash",
  "channelId": "YOUR_CHANNEL_ID",
  "merchantReference": "REDEEM-2026-05-000456"
}

Field	Required	Description
productCode	Yes	Code of the redemption product. See Product Code Format.
amount	Yes	Amount to redeem in ZAR. Pass the voucher face value, or 0 to redeem the full remaining balance.
voucherPin	Yes	The voucher PIN presented by the customer.
mobileNumber	Cond.	Customer mobile number (digits only, without country code — e.g. "821234567"). Required for certain redemption products.
paymentMethod	Yes	Payment method (e.g. cash).
channelId	Yes	Your channel identifier. See How To Find Your Channel ID below.
merchantReference	Yes	Acts as the idempotency key. See Idempotency below.

How To Find Your Channel ID

Your channelId is shown in the Pagamio merchant dashboard:

Sign in → My User → Channels tab

Idempotency

The merchantReference field is the idempotency key for this endpoint. See Idempotency & Retries for the full retry pattern.

---

Success Response (200 OK)

{
  "transactionId": "c1a72041-8b33-4f92-a11b-293de7001234",
  "responseCode": "0",
  "responseMessage": "Purchase successful",
  "responseDateTime": "2026-05-17T09:14:32.123456789",
  "successful": true,
  "receipt": {
    "voucherID": "12345678",
    "amount": "10.00",
    "voucherBalance": "0.00"
  }
}

Field	Description
transactionId	Unique Pagamio reference for this redemption transaction.
responseCode	"0" indicates success.
successful	true when the voucher was accepted and redeemed.
receipt	Redemption details. Fields present depend on the product configuration.
voucherID	The voucher identifier at the aggregator.
amount	Amount redeemed.
voucherBalance	Remaining balance on the voucher after redemption.

---

Error Responses

Voucher not found

{
  "responseCode": "1010",
  "responseMessage": "Invalid product"
}

Voucher already used

{
  "transactionId": "549fe843-79e3-44f4-a2e4-8a464d1b06c1",
  "responseCode": "1151",
  "responseMessage": "The voucher has already been used",
  "responseDateTime": "2026-05-17T13:31:35.511593",
  "successful": false
}

Voucher expired

{
  "responseCode": "1200",
  "responseMessage": "Provider processing error"
}

Voucher PIN missing

{
  "responseCode": "1001",
  "responseMessage": "voucherPin is required for OTT voucher redemption"
}

Insufficient balance (wallet)

{
  "responseCode": "1103",
  "responseMessage": "Insufficient balance. Available: R0.00"
}

For the full list of error codes, see the Error Code Reference.

---

How Voucher Validation Works

Voucher validity is enforced by the upstream aggregator, not by Pagamio. When you submit a PIN:

1. Pagamio forwards the PIN to the aggregator's redemption API.
2. The aggregator checks whether the voucher exists, is active, and has not already been used or cancelled.
3. Pagamio maps the aggregator's response code to a standardised responseCode and returns it to you.

This means you do not need to pre-validate vouchers before calling /redeem — the endpoint handles all voucher-state checks in a single call. If the voucher is invalid for any reason, the transaction is recorded as FAILED and your wallet is not debited.

---

Last updated: May 2026