Nigeria

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 / PalmPay · Bank transfer with BVN · Provider payment page · Airtel

Several 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 / PalmPay / Pay Attitude 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
`phone`	string	⚠️ Depends on the method	Payer phone number, e.g. `2348012345678`. Required for OPay and PalmPay
`email`	string	⚠️ Depends on the method	Payer email
`firstName`	string	⚠️ Depends on the method	First name
`lastName`	string	⚠️ Depends on the method	Last name
`bankAccount`	string	⚠️ Depends on the method	Payer BVN (Bank Verification Number), 11 digits
`bankCode`	string	⚠️ Depends on the method	Code of the payer's bank
`country`	string	❌ No	Country code `NG`

The required set depends on the method enabled on your terminal. If a field it needs is missing, the order is rejected with 400 listing the fields. Without a phone the payer email is used as the payer ID, so send at least one of them.

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",
    "phone": "2348012345678",
    "email": "john.doe@example.com"
  }
}

Getting the account details via API (H2H)

To show the details on your own page instead of paymentLink, request them after creating the order:

POST /v1/orders/{orderId}/h2h/bank-transfer

curl -X POST "https://api.1capital.capital/v1/orders/{orderId}/h2h/bank-transfer" \
  -H "x-api-token: YOUR_API_TOKEN"

The first call creates the payment at the provider; repeated calls return the same details. Do not send the payer to paymentLink as well: it shows the same account.

{
  "accountNumber": "1597534560",
  "accountName": "EXAMPLE TECH LTD",
  "bankName": "GLOBUS BANK",
  "bankCode": null,
  "amount": "10000",
  "currency": "NGN",
  "details": {
    "account_name": "EXAMPLE TECH LTD",
    "account_number": "1597534560",
    "bank_name": "GLOBUS BANK",
    "transfer_amount": "10000"
  }
}

Field	Description
`accountNumber`	Account to transfer to
`accountName`	Account holder name
`bankName`	Bank name
`bankCode`	Bank code, if the provider returned it
`amount`	Amount to transfer, if the provider returned it
`details`	All details as returned by the provider. Field names differ between banks: show the payer every field

Status	When
`400`	The method enabled on the terminal does not issue account details, or the order is a test one
`404`	Order not found
`409`	The order is no longer `CREATED` or `PENDING`
`503`	The provider has not issued the details yet: retry in a few seconds

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

Bank transfer, OPay, PalmPay, Pay Attitude or card on the provider page: the payer is redirected to paymentLink and completes the payment there.

Customer fields

Field	Type	Required	Description
`phone`	string	⚠️ Depends on the method	Payer phone number, e.g. `2348012345678`
`email`	string	⚠️ Depends on the method	Payer email
`firstName`	string	⚠️ Depends on the method	First name
`lastName`	string	⚠️ Depends on the method	Last name
`country`	string	❌ No	Country code `NG`

The required set depends on the operator enabled on your terminal. If a field it needs is missing or the phone does not match the country format, the order is rejected with 400 listing the fields. Send firstName, lastName, email and phone whenever you have them.

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",
    "phone": "2348012345678",
    "email": "john.doe@example.com"
  }
}

Send the payer to paymentLink: the payment request goes to Airtel when the link is opened, and the payer confirms it on their phone. The page waits for the result and shows it; the final status also comes to your callbackUrl.

Customer fields

Field	Type	Required	Description
`phone`	string	✅ Yes	Payer phone number, e.g. `2348012345678`
`country`	string	❌ No	Country code `NG`

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",
    "phone": "2348012345678",
    "email": "john.doe@example.com"
  }
}

Nigeria

Before you start

Authorization

Create payment

Overview

What is different from a regular order

Customer fields

Request example

Customer fields

Request example

Getting the account details via API (H2H)

Customer fields

Request example

Customer fields

Request example

Customer fields

Request example

Response

Order object fields

Next steps

Order status and webhooks

Payments by country

On this page

Nigeria

Authorization

Create payment

Response example

Order object fields

Order status and webhooks

Payments by country

On this page