Vouchers

The Vouchers API allows you to generate redeemable codes for products like airtime, data, and combo bundles. Unlike the Transactions API which directly provisions a product to a customer's account, this API provides a code that the customer can redeem at their convenience.

To ensure transactional integrity, especially in point-of-sale (POS) environments, creating a voucher is a mandatory two-step process:

• Generate the voucher to get the code.
• Confirm (or Reverse) the transaction to activate the code.

❗️

Critical: The Two-Step Workflow
A voucher is not active or redeemable when it is first created. You must make a second API call to CONFIRM the transaction after you have successfully taken payment and issued a receipt. If the transaction fails for any reason (e.g., payment declined, printer error), you must REVERSE it.

The Two-Step Workflow

Step 1: Generate the Voucher

First, you make a request to generate the voucher. The system creates the voucher details, including the customer-facing code, and places it in a temporary AUTHORISED state.

POST /vouchers

The API will respond with a voucher object which includes a unique id (for the next step) and the code to be printed on the customer's receipt.

Step 2: Confirm or Reverse the Voucher

After receiving a successful response from the generation step, you must immediately make a second call to update the voucher's status.

PATCH /vouchers/:id

You will use the id from the Step 1 response in the URL path. In the request body, you will set the state to one of two values:

• CONFIRMED: This activates the voucher, making it redeemable for the customer. This is the standard final step for a successful sale.
• REVERSED: This permanently cancels the voucher. This should be used if the customer's payment fails or the transaction is aborted after the voucher code has been generated.