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

Parameter	Type	Required
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`
currency `Account currency. Use 'USD' for USD virtual accounts`	`string`
personalInformation `Business owner details. Required for USD business accounts`	`object`
businessInformation `Company details. Required for USD business accounts`	`object`
complianceInformation `KYB documents array. Required for USD business accounts`	`array`

📘

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

Request (Business - USD)

USD business accounts require additional KYC/KYB fields: personalInformation, businessInformation, and complianceInformation. Set currency to USD and type to BUSINESS.

personalInformation fields

Parameter	Type	Required
gender	`string`	✅
primaryNationality	`string`	✅
ownershipPercentage	`number`	✅
address.streetLine1	`string`	✅
address.streetLine2	`string`
address.city	`string`	✅
address.state	`string`	✅
address.country	`string`	✅
address.subdivision	`string`
address.postalCode	`string`	✅
identifyingInformation.type `e.g. drivers_license, passport`	`string`	✅
identifyingInformation.number	`string`	✅
identifyingInformation.issuingCountry	`string`	✅
identifyingInformation.idFrontImage `URL to ID front`	`string`	✅
identifyingInformation.idBackImage `URL to ID back`	`string`	✅
proofOfAddress.name	`string`	✅
proofOfAddress.url	`string`	✅
proofOfAddress.description	`string`

businessInformation fields

Parameter	Type	Required
description	`string`
registrationNumber	`string`	✅
email	`string`	✅
type	`string`	✅
industry	`string`	✅
dateOfIncorporation	`string`	✅
website	`string`
publiclyTraded	`boolean`	✅
accountPurpose	`string`	✅
annualRevenue	`string`	✅
estimatedMonthlyDeposits	`string`	✅
estimatedMonthlyWithdrawals	`string`	✅
sourceOfFunds	`string`	✅
address.streetLine1	`string`	✅
address.streetLine2	`string`
address.city	`string`	✅
address.state	`string`	✅
address.country	`string`	✅
address.subdivision	`string`
address.postalCode	`string`	✅
taxInformation.taxId	`string`	✅
taxInformation.taxIdType `e.g. SSN, TIN`	`string`	✅
taxInformation.taxCountry	`string`	✅

complianceInformation fields (array of objects)

Parameter	Type	Required
name	`string`	✅
url	`string`	✅
description	`string`

📘

Accepted complianceInformation document names: CAC Status Report, Certificate of Incorporation, Tax Identification Certificate / Tax ID Verification.

Virtual Accounts/Create Business USD 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": "John",
      "lastName": "Doe",
      "bvn": "22528807864",
      "customerEmail": "john.doe@example.com",
      "reference": "4b0d8c61-7d5d-4a4c-b6e7-123456789abc",
      "bank": "providus",
      "phoneNumber": "08134288809",
      "dateOfBirth": "1990-01-01",
      "type": "BUSINESS",
      "rcNumber": "0123456",
      "businessLegalName": "Acme Healthcare Limited",
      "currency": "USD",
      "personalInformation": {
        "address": {
          "streetLine1": "123 Main Street",
          "streetLine2": "Suite 100",
          "city": "Lagos",
          "state": "Lagos",
          "country": "Nigeria",
          "subdivision": "Lagos",
          "postalCode": "07008"
        },
        "gender": "male",
        "primaryNationality": "Ghana",
        "identifyingInformation": {
          "type": "drivers_license",
          "number": "GHA-070-1212",
          "issuingCountry": "Ghana",
          "idFrontImage": "https://example.com/id-front.jpg",
          "idBackImage": "https://example.com/id-back.jpg"
        },
        "proofOfAddress": {
          "name": "utility_bill",
          "url": "https://example.com/utility-bill.pdf",
          "description": "Recent utility bill"
        },
        "ownershipPercentage": 90
      },
      "businessInformation": {
        "description": "Healthcare services provider",
        "registrationNumber": "REG-123456",
        "email": "business@example.com",
        "type": "individual",
        "industry": "Healthcare",
        "dateOfIncorporation": "2020-01-01",
        "address": {
          "streetLine1": "123 Business Street",
          "streetLine2": "Floor 2",
          "city": "Lagos",
          "state": "Lagos",
          "country": "Nigeria",
          "subdivision": "Lagos",
          "postalCode": "07008"
        },
        "website": "https://acmehealthcare.com",
        "publiclyTraded": false,
        "accountPurpose": "Charitable donations",
        "annualRevenue": "Less than USD 1k",
        "estimatedMonthlyDeposits": "USD 1k - USD 50k",
        "estimatedMonthlyWithdrawals": "USD 2.5M - USD 5M",
        "sourceOfFunds": "equity crowdfunding",
        "taxInformation": {
          "taxId": "123456789",
          "taxIdType": "SSN",
          "taxCountry": "Ghana"
        }
      },
      "complianceInformation": [
        {
          "name": "CAC Status Report",
          "url": "https://example.com/cac-status-report.pdf",
          "description": "CAC Status Report"
        },
        {
          "name": "Certificate of Incorporation",
          "url": "https://example.com/certificate-of-incorporation.pdf",
          "description": "Certificate of Incorporation"
        },
        {
          "name": "Tax Identification Certificate / Tax ID Verification",
          "url": "https://example.com/tax-certificate.pdf",
          "description": "Tax Identification Certificate / Tax ID Verification"
        }
      ]
    }'

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

Response Fields

The data object contains the virtual account details.

Field	Type	Description
id	`string (UUID)`	Unique identifier for the virtual account.
createdAt	`string (ISO 8601)`	Timestamp when the virtual account was created.
updatedAt	`string (ISO 8601)`	Timestamp when the virtual account was last updated.
currency	`string`	Account currency. Either `usd` or `ngn`.
customerId	`string (UUID)`	Unique identifier of the customer that owns the account.
reference	`string`	Unique account reference.
status	`string`	Current status of the virtual account. One of `active`, `inactive`, `pending`, `needs_verification`.
type	`string`	USD accounts only. Virtual account type — `SWIFT` or `WIRE`. Not returned for NGN accounts.
accountName	`string`	Name associated with the virtual account.
bankName	`string`	Name of the financial institution providing the account.
accountNumber	`string`	Virtual account number.
bank	`string`	Bank code or SWIFT/BIC code.

Terminate card [POST]Get virtual account [GET]