API Reference
Virtual Accounts
Create virtual account [POST]

Create a virtual account

https://sandboxapi.onbrails.com/api/v1/virtual-accounts (opens in a new tab)

You can create virtual accounts for both individual and business customers. For business accounts, additional fields (rcNumber and businessLegalName) are required.

Body Parameters

ParameterTypeRequired
firstName
Enter first name		string✅
lastName
Enter last name		string✅
bvn
Enter user's BVN		string✅
dateOfBirth
Enter customer date of birth. It is only required when bank is 'providus'		string
customerEmail
Enter Customer Email		string✅
reference
Enter reference for identification		string✅
bank
Bank should be either 'safehaven' or 'providus'		string✅
phoneNumber
Enter phone number		string✅
type
Account type. Either 'INDIVIDUAL' (default) or 'BUSINESS'		string
rcNumber
Business registration number. Required when type is 'BUSINESS'		string
businessLegalName
Legal name of the business. Required when type is 'BUSINESS'		string
📘

When creating a business virtual account, set type to BUSINESS and include both rcNumber and businessLegalName. These fields are required for business accounts and will be rejected if missing.

Request (Individual)

Virtual Accounts/Create Individual Account [POST]
curl --request POST \
   --url https://sandboxapi.onbrails.com/api/v1/virtual-accounts \
   --header 'Authorization: Bearer API-KEY' \
   --header 'accept: application/json' \
   --header 'content-type: application/json' \
   --data '{
      "firstName": "Centino",
      "lastName": "Jen",
      "bvn": "00000000000",
      "dateOfBirth": "2025-03-26",
      "customerEmail": "email@email.com",
      "reference": "0ieoeuy3474",
      "bank": "providus",
      "phoneNumber": "0000000000"
    }'

Request (Business)

Virtual Accounts/Create Business Account [POST]
curl --request POST \
   --url https://sandboxapi.onbrails.com/api/v1/virtual-accounts \
   --header 'Authorization: Bearer API-KEY' \
   --header 'accept: application/json' \
   --header 'content-type: application/json' \
   --data '{
      "firstName": "Centino",
      "lastName": "Jen",
      "bvn": "00000000000",
      "dateOfBirth": "2025-03-26",
      "customerEmail": "email@email.com",
      "reference": "biz_ref_001",
      "bank": "providus",
      "phoneNumber": "0000000000",
      "type": "BUSINESS",
      "rcNumber": "RC123456",
      "businessLegalName": "Acme Technologies Ltd"
    }'

Responses

🟢 200 - Individual account result
{
  "status": true,
  "message": "Virtual account successfully generated",
  "data": {
      "id": "a2296d18-ea09-45c3-9a58-d179b54167c9",
      "createdAt": "2025-02-17T13:56:31.790Z",
      "updatedAt": "2025-02-17T13:56:31.790Z",
      "currency": "ngn",
      "bank": "providus",
      "customerId": "2da22eba-35ea-4a14-936f-18b047498393",
      "bankName": "GLOBUS Bank",
      "reference": "0ieoeuy3474",
      "accountName": "Centino Jen",
      "accountNumber": "6563002662",
      "status": "active"
  }
}
Terminate card [POST]Get virtual account [GET]