Nigeria
Bank transfers and OPay wallet payments in NGN
Before you start
Authorization
How to sign your requests with the API token.
Create payment
The base order request that this page extends.
This payment method is not enabled for all merchants. Check availability with your manager.
Overview
| Currency | Country code | Payment methods |
|---|---|---|
NGN | NG | Bank transfer with ID document · Bank transfer to a one-time account / OPay · Bank transfer with BVN |
Three integration options are available in Nigeria. They use different providers and require different payer data; which one is enabled for your account is defined by your terminal settings.
Not sure which option you have? Ask your manager.
What is different from a regular order
The order is created through the standard POST /v1/orders endpoint. The base fields (amount, currency, successUrl, failUrl, callbackUrl, etc.) are the same as for a regular order; on top of them you pass the customer object with payer details.
| Field | Type | Description |
|---|---|---|
customer | object | Payer details. The required set is listed below |
The payer is redirected to paymentLink and completes the transfer on the provider page. The payer's identity document is required.
The externalUserId field is required for this payment method.
Customer fields
| Field | Type | Required | Description |
|---|---|---|---|
country | string | ✅ Yes | Country code, always NG |
phone | string | ✅ Yes | Payer phone number |
document | string | ✅ Yes | Payer document number |
documentType | string | ✅ Yes | Document type, e.g. ID |
email | string | ✅ Yes | Payer email |
firstName | string | ✅ Yes | First name |
lastName | string | ✅ Yes | Last name |
Request example
{
"purpose": "Payment for order #1234",
"amount": "1000.5",
"currency": "NGN",
"externalId": "external_id",
"externalUserId": "external_user_id",
"successUrl": "https://example.com/success",
"failUrl": "https://example.com/fail",
"callbackUrl": "https://example.com/webhooks/payments",
"isFeeOnUser": false,
"customer": {
"firstName": "John",
"lastName": "Doe",
"country": "NG",
"phone": "2348012345678",
"email": "john.doe@example.com",
"document": "A123456789",
"documentType": "ID"
}
}paymentLink opens a page with temporary bank account details (bank name, account number, account name). The payer makes a manual transfer to these details from their banking app or OPay wallet.
The account details are one-time and valid only for the exact order amount. Warn the payer to transfer the exact amount in a single payment. Otherwise processing may take much longer or the funds may be lost.
Customer fields
| Field | Type | Required | Description |
|---|---|---|---|
country | string | ✅ Yes | Country code, always NG |
email | string | ✅ Yes | Payer email |
phone | string | For OPay | Payer phone number, required for OPay |
firstName | string | ❌ No | First name |
lastName | string | ❌ No | Last name |
Request example
{
"purpose": "Payment for order #1234",
"amount": "10000",
"currency": "NGN",
"externalId": "external_id",
"externalUserId": "external_user_id",
"successUrl": "https://example.com/success",
"failUrl": "https://example.com/fail",
"callbackUrl": "https://example.com/webhooks/payments",
"isFeeOnUser": false,
"customer": {
"firstName": "John",
"lastName": "Doe",
"country": "NG",
"phone": "2349061239999",
"email": "john.doe@example.com"
}
}The payer is redirected to paymentLink and completes the transfer on the provider page. The payer's BVN (Bank Verification Number) and bank code are required.
Customer fields
| Field | Type | Required | Description |
|---|---|---|---|
country | string | ✅ Yes | Country code, always NG |
firstName | string | ✅ Yes | First name |
lastName | string | ✅ Yes | Last name |
phone | string | ✅ Yes | Payer phone number |
email | string | ✅ Yes | Payer email |
bankAccount | string | ✅ Yes | Payer BVN (Bank Verification Number), 11 digits |
bankCode | string | ✅ Yes | Code of the payer's bank |
Request example
{
"purpose": "Payment for order #1234",
"amount": "1000.5",
"currency": "NGN",
"externalId": "external_id",
"externalUserId": "external_user_id",
"successUrl": "https://example.com/success",
"failUrl": "https://example.com/fail",
"callbackUrl": "https://example.com/webhooks/payments",
"isFeeOnUser": false,
"customer": {
"firstName": "John",
"lastName": "Doe",
"country": "NG",
"phone": "2348012345678",
"email": "john.doe@example.com",
"bankAccount": "22123456789",
"bankCode": "058"
}
}Response
The response is a standard order object. The order is created with the CREATED status; redirect the payer to paymentLink to complete the payment.