Esc

Virtual accounts

Give a customer a permanent 10-digit account number. Money they transfer to it is credited to your Gafiapay balance.

Generate a virtual account

Create a new virtual account number for your customer.

POST /account/generate
Send one ID number

Send one of bvn, nin or businessNumber. If you send more than one, the API uses businessNumber first, then bvn, then nin. If you send none, your own business's verified BVN, NIN or CAC number is used.

Headers

x-api-key string required
Your API key.
x-signature string required
Request signature. See Signing a request.
x-timestamp string required
Current Unix time in milliseconds.
Content-Type string required
application/json

Body

name string required
Customer's full name.
email string required
Customer's email address.
bvn string one ID number
Customer's BVN, 11 digits.
nin string one ID number
Customer's NIN, 11 digits.
businessNumber string one ID number
CAC registration number, for example RC1234567 or BN1234567. Use it when the customer is a business.

Errors

StatusExample messageWhen
400bvn must be 11 digitsAn ID number is in the wrong format.
400Reason from the bankThe bank couldn't verify the ID number you sent.
500Reason in errorWe couldn't reach the bank. Try again later.
curl -X POST 'https://api.gafiapay.com/api/v1/external/account/generate' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: your_api_key' \
  -H 'x-timestamp: 1678901234567' \
  -H 'x-signature: generated_signature' \
  -d '{
    "name": "John Doe",
    "email": "john@example.com",
    "bvn": "22345678901"
  }'
{
  "status": "success",
  "data": {
    "bankName": "Palmpay",
    "accountNumber": "1234567890",
    "accountName": "John Doe",
    "userName": "John Doe"
  }
}

Notes

Account reuse

Each email gets one permanent account on your business. If you call this endpoint again with an email that already has one, you won't get a second account: the existing one is updated and returned. The account number can change when this happens, so always save the number from the latest response.

Account numbers

Account numbers are 10 digits. Show your customer the accountNumber, bankName and accountName from the response so they can transfer to it.

ID numbers

Temporary accounts follow the same rules for bvn, nin and businessNumber.

GafiaPayGafiaPayDocs
Guide for AI agents Dashboard