API Reference · Wallets & accounts

Customer Bank Accounts

Permanent account numbers for your customers. Every transfer into one is credited to you as a charge from that customer, with the usual fee.

The customer_bank_account object

Represents a customer_bank_account entity in the rafiqPay system.

Field	Type & Flags	Description
id	string	Account ID (cba_...).
customerId	string	The customer it belongs to.
mode	enum	live \| test. Test account numbers start with 99.
accountNumber	string	10-digit account number the customer sends money to.
accountName	string	The name the customer’s bank shows for the account.
bankName	string	The bank the account is at.
createdAt	string	When the account was opened (ISO 8601).

Example customer_bank_account JSON

customer_bank_account example payload

{
  "id": "cba_01J9KANZU5",
  "object": "customer_bank_account",
  "customerId": "cus_amina_01",
  "mode": "live",
  "accountNumber": "0123456781",
  "accountName": "Kanzu Learning - Amina Bello",
  "bankName": "GTBank",
  "createdAt": "2026-11-07T09:00:00.000Z"
}

Endpoints & Operations

POST/v1/customers/:id/virtual-accountsIn plan 035

Open a customer bank account

Opens a permanent account for the customer. The customer must already have an email. The details must match the customer’s BVN. The BVN is passed to the bank and is never stored or returned. Pass ?mode=test for a test account.

Request Parameters

Parameter	Type	Requirement	Description
firstName	string	Required	As on the BVN.
lastName	string	Required	As on the BVN.
middleName	string	Optional	As on the BVN.
phone	string	Required	10 to 14 digits, with or without +.
dateOfBirth	string	Required	YYYY-MM-DD, as on the BVN.
gender	enum	Required	male \| female.
address	string	Required	5 to 200 characters.
bvn	string	Required	11 digits. Passed to the bank, never stored.

Request Example

POST /v1/customers/:id/virtual-accounts

cURL · v1

curl -X POST "https://api.rafiqpay.net/v1/customers/:id/virtual-accounts" \
  -H "Authorization: Bearer rp_test_sk_kanzu_9f8a7b6c5d4e3f2a" \
  -H "Idempotency-Key: idem_open-customer-account_01" \
  -H "Content-Type: application/json" \
  -d '{
  "firstName": "Amina",
  "lastName": "Bello",
  "phone": "+2348034567890",
  "dateOfBirth": "1994-03-18",
  "gender": "female",
  "address": "12 Admiralty Way, Lekki, Lagos",
  "bvn": "22200000001"
}'

Response (200 OK)

Response payload

{
  "id": "cba_01J9KANZU5",
  "object": "customer_bank_account",
  "customerId": "cus_amina_01",
  "mode": "live",
  "accountNumber": "0123456781",
  "accountName": "Kanzu Learning - Amina Bello",
  "bankName": "GTBank",
  "createdAt": "2026-11-07T09:00:00.000Z"
}

GET/v1/customers/:id/virtual-accountsIn plan 035

List a customer’s bank accounts

Lists the customer’s permanent accounts, live and test.

Request Example

GET /v1/customers/:id/virtual-accounts