> ## Documentation Index
> Fetch the complete documentation index at: https://flutterwaveinc.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 1Voucher
> Learn about 1Voucher, a prepaid payment method.
We recommend checking out the [introductory section](/payment-api/introduction)
to understand the basics of direct charge first. This guide assumes you've
read that.
[1Voucher](https://shop.1voucher.co.za/) 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](https://www.1voucher.co.za/where-to-spend) 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 Tip**
For assistance with any of your requests, contact our support team via email at [hi@flutterwavego.com](mailto: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](/api-reference/charges/card).
**Integration Tip**
Read the 1Voucher API [reference](/api-reference/charges/card) for the full list of supported parameters.
```json Sample Request theme={null}
{
"tx_ref": "YOUR_PAYMENT_REFERENCE",
"amount": "1",
"currency": "ZAR",
"phone_number": "27xxxxxxxx7",
"email": "user@example.com",
"pin": "1234567890"
}
```
Response should look like this:
```json 200 OK theme={null}
{
"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"
}
}
}
```
```json 401 Unauthorized theme={null}
{
"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.
```json theme={null}
{
"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](/api-reference/transactions/verify-a-transaction).
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](/transaction-verification) and [webhook](/webhooks) guides. These resources provide comprehensive information to assist you in completing the transaction on your system.
```json Sample Webhook theme={null}
{
"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"
}
```