Have you ever integrated our payment API into your product? Help us improve the developer experience for you and everyone by taking this short survey, get started here

1Voucher

Integration tip

Hello there👋. We recommend reading the overview section first to understand the basics of making a direct charge. 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🇿🇦.

Pre-requisites

Here are some requirements to have in place before you start your integration:

  1. Check that your account is live and verified.
  2. Request to enable this feature on your account.
Integration tip

For 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 with the customer and transaction information.
  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 initiate the payment, collect your customer's information - email address and phone number. Pass the customer information with the transaction details i.e. reference, currency and amount to the 1Voucher charge endpoint.

Integration tip

Read 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"
}

{
  "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"
    }
  }
}

{
   "status": "error",
   "message": "Invalid Authorization key",
   "data": null
}

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 tip

It's considered 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 verify transaction endpoint.
  2. Use the final status from your transaction webhook.
Integration tip

It 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.

 {
  "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"
}
Loading...