Skip to main content
We recommend checking out the introductory section to understand the basics of direct charge first. This guide assumes you’ve read that.
1Voucher is a prepaid payment method that allows users to make online purchases and transactions without using a credit or debit card. It works by providing customers with a unique 16-digit PIN code that can be entered during checkout on supported websites. The payment is deducted from the total value of the voucher, similar to how a gift card or prepaid card works. 1voucher is exclusively used for payments in South Africa 🇿🇦.

​
Prerequisites

To start your integration, you need the following:
  1. Check that your account is live and verified.
  2. Request to enable this feature on your account.
Integration TipFor assistance with any of your requests, contact our support team via email at hi@flutterwavego.com.

​
Payment Flow

1Voucher payments go through three (3) stages before completion:
  1. Initiation - The merchant initiates the payment on behalf of the customer using the customer’s information and transaction details.
  2. PIN Validation - After the transaction is initiated, we charge the voucher PIN for the transaction and issue a new PIN to the customer for future transactions.
  3. Confirmation - The merchant confirms the transaction status. If successful, they can provide value or reinitiate the payment if unsuccessful.

​
Step 1: Initiating the Charge

To initate the payment, collect your customer’s information - email and phone_number. Pass the customer information with the transaction details i.e. reference, currency and amount to the 1Voucher charge endpoint.
Integration TipRead the 1Voucher API reference for the full list of supported parameters.
{
  "tx_ref": "YOUR_PAYMENT_REFERENCE",
  "amount": "1",
  "currency": "ZAR",
  "phone_number": "27xxxxxxxx7",
  "email": "user@example.com",
  "pin": "1234567890"
}
Response should look like this: 
{
  "status": "success",
  "message": "Charge successful",
  "data": {
    "id": 1362136900,
    "tx_ref": "YOUR_PAYMENT_REFERENCE",
    "flw_ref": "IUYG0857317139626658",
    "device_fingerprint": "N/A",
    "amount": 1,
    "charged_amount": 1,
    "app_fee": 0.07,
    "merchant_fee": 0,
    "processor_response": "Transaction Successful",
    "auth_model": "AUTH",
    "currency": "ZAR",
    "ip": "52.18.161.235",
    "narration": "TEST_PAYMENT",
    "status": "successful",
    "auth_url": "NO-URL",
    "payment_type": "1voucher",
    "fraud_status": "ok",
    "charge_type": "normal",
    "created_at": "2024-04-24T12:44:25.000Z",
    "account_id": 18428,
    "meta_data": {
      "change_voucher": {
        "amount": 51.86,
        "pin": "1234567890123456",
        "serial": "20240424144460200153",
        "expiry": "2027-04-24T14:44:26+02:00"
      }
    },
    "customer": {
      "id": 854597931,
      "phone_number": "27xxxxxxxx7",
      "name": "Anonymous customer",
      "email": "user@example.com",
      "created_at": "2024-04-24T12:44:25.000Z"
    }
  }
}

​
Step 2: Retrieving the new Voucher PIN

When the voucher is charged, the current PIN becomes invalid, and a new one is generated. In the charge response, we provide the new PIN as data.meta_data.pin.
Integration TipIt’s best practice to display the current balance and expiry of the voucher to the customer. You can achieve this by returning the balance (meta_data.amount) and expiry(meta_data.expiry) along with the new PIN.
{
  "status": "",
  "message": "",
  "data": {
    "tx_ref": "",
    ...
    "meta_data": {
      "change_voucher": {
        "amount": 51.86,
        "pin": "1896682868182894",
        "serial": "20240424144460200153",
        "expiry": "2027-04-24T14:44:26+02:00"
      }
    },
    "customer": {
      ...
    }
  }
}

​
Step 3: Verifying your transaction

Once the transaction is completed, you need to determine it’s final status. There are two ways to query the transaction’s final status.
  1. Query the verified transaction endpoint.
  2. Use the final status from your transaction webhook.
Integration TipIt is very important to confirm the customer’s name, transaction status and amount before providing value for your transaction.
We discuss these options in more details in the transaction verification and webhook guides. These resources provide comprehensive information to assist you in completing the transaction on your system.
Sample Webhook
 {
  "id": 4963659,
  "txRef": "YOUR_PAYMENT_REFERENCE",
  "flwRef": "FLWTK43726MCK1710339922867",
  "orderRef": "URF_1710339922628_1685735",
  "paymentPlan": null,
  "paymentPage": null,
  "createdAt": "2024-03-13T14:25:22.000Z",
  "amount": 50,
  "charged_amount": 50,
  "status": "successful",
  "IP": "54.75.161.64",
  "currency": "ZAR",
  "appfee": 2.25,
  "merchantfee": 0,
  "merchantbearsfee": 1,
  "customer": {
    "id": 2371343,
    "phone": "8081806271",
    "fullName": "Anonymous customer",
    "customertoken": null,
    "email": "user@example.com",
    "createdAt": "2024-03-13T14:21:45.000Z",
    "updatedAt": "2024-03-13T14:21:45.000Z",
    "deletedAt": null,
    "AccountId": 77778
  },
  "entity": {
    "id": "NO-ENTITY"
  },
  "event.type": "1VOUCHER_TRANSACTION"
}