1Voucher

📘

Getting Started

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.

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 Tip

For assistance with any of your requests, contact our support team via email at [email protected].

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 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": "[email protected]",
  "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": "[email protected]",
      "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 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. Verify a transaction endpoint.
2. Use the final status from your transaction webhook.

🚧

Confirmation

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": "[email protected]",
    "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"
}