What are Virtual Bank Accounts?
Virtual Bank Accounts are dedicated bank account numbers that allow your business and your customers to receive money. When someone sends funds to a Virtual Bank Account, the money is automatically credited to the associated wallet, and you are notified via a webhook.
They are available in NGN, GBP, EUR, and USD.
How to create a Virtual Bank Account
- Endpoint:
/virtual-bank-account
- Method:
POST
- Purpose: Generate a new Virtual Bank Account linked to a wallet.
For NGN, the Virtual Bank Account is typically activated immediately and the response will return with a SUCCESSFUL status along with the account details.
For GBP, EUR, and USD, the account is created asynchronously. The response will return with a PENDING status. Once the account is fully activated, you will receive a virtual_account.ready webhook with the account details (account number, bank name, etc.). If the account creation fails or is rejected, you will receive a virtual_account.failed or virtual_account.rejected webhook instead.
For GBP, EUR, and USD, Virtual Bank Account creation requires a verified customer of type individual. Business-type customers are not supported for these currencies.
In the development environment, only NGN Virtual Bank Accounts settle.
Understanding identification types (TIN)
When creating a Virtual Bank Account (particularly for USD), your customer needs a tin (Tax Identification Number) value on their profile. However, “TIN” is a generic term — what it actually represents depends on the customer’s country and whether they are an individual or a business.
For example:
| Country | Customer type | What to collect | Example label |
|---|
| US | Individual | Social Security Number | SSN |
| US | Business | Employer Identification Number | EIN |
| NG | Individual | Bank Verification Number | BVN |
| GB | Individual | National Insurance Number | NINO |
| CA | Individual | Social Insurance Number | SIN |
- Call Get identification type with the customer’s
country and type (or their customer_id if you already have one).
- Use the returned
label to display the correct field name in your UI (e.g. “Enter your Social Security Number” instead of “Enter your TIN”).
- Save the value your customer provides as the
tin field when creating or updating the customer.
- Proceed to create the Virtual Bank Account.
Individual and business customers in the same country often require different identification types. Always pass the correct type parameter when looking up the identification type.
Quick answers
- Which Virtual Bank Accounts settle in development? Only NGN Virtual Bank Accounts settle in the development environment.
- Should the customer’s country match the identity document? Yes. The customer’s
country must match the identity document submitted for KYC.
- How do I know the correct
tin label or field? See Understanding identification types above, or call the Get identification type endpoint.
Before creating a Virtual Bank Account, ensure the following prerequisites are in place. Requirements vary depending on the currency.
All Currencies
NGN
GBP
EUR
USD
Wallet must existYou must have a wallet in the currency you want to create a Virtual Bank Account for. Pass a valid wallet_id in your request.No duplicate accountsYou cannot create a second Virtual Bank Account for the same customer and wallet combination. If one already exists, the request will be rejected.Customer country and identity document must matchFor any customer-backed Virtual Bank Account, the customer’s country must match the country on the identity document submitted for KYC.
Account name is requiredFor NGN Virtual Bank Accounts, you must provide an account_name in your request. This is the name that will appear on the virtual account.Customer is optionalYou can create NGN Virtual Bank Accounts with or without a customer_id. If you provide a customer_id, the customer must belong to your business.Duplicate check by account nameWhen creating without a customer, the system checks for duplicates by account_name. You cannot create two Virtual Bank Accounts with the same name on the same wallet.
Customer is requiredYou must provide a customer_id. The customer must be verified and of type individual.Customer information must be completeThe following fields must be present on the customer’s profile and KYC data before creating a GBP Virtual Bank Account:
- First Name
- Last Name
- Email
- Country
- ID Type
- ID Number
- Date of Birth
- ID Expiry Date
- Zip Code
- City
- Street
If any of these are missing, the request will fail and the response will tell you which fields are missing.Name formatThe customer’s first name and last name must contain only letters, hyphens, periods, apostrophes, and spaces. Names with numbers or special characters will be rejected.Street address formatThe customer’s street address must contain only alphanumeric characters and the following: - / # ( ) ' , .ID must not be expiring soonThe customer’s identity document must have an expiry date at least one month from today.Valid postal codeThe customer’s zip code must be a valid postal code for their country. Customer is requiredYou must provide a customer_id. The customer must be verified and of type individual.Customer information must be completeThe following fields must be present on the customer’s profile and KYC data before creating an EUR Virtual Bank Account:
- First Name
- Last Name
- Email
- Country
- ID Type
- ID Number
- Date of Birth
- ID Expiry Date
- Zip Code
- City
- Street
If any of these are missing, the request will fail and the response will tell you which fields are missing.Name formatThe customer’s first name and last name must contain only letters, hyphens, periods, apostrophes, and spaces. Names with numbers or special characters will be rejected.Street address formatThe customer’s street address must contain only alphanumeric characters and the following: - / # ( ) ' , .ID must not be expiring soonThe customer’s identity document must have an expiry date at least one month from today.Valid postal codeThe customer’s zip code must be a valid postal code for their country. Customer is requiredYou must provide a customer_id. The customer must be verified and of type individual.Identity document must be uploadedThe customer must have an identity document file uploaded before you can create a USD Virtual Bank Account.US customers: Driver’s License or Passport onlyIf the customer’s country is the US, they must have a Driver’s License or Passport as their identity document. National ID cards are not accepted for US-based customers.Customer information must be completeUSD Virtual Bank Accounts require the most customer information. The following fields must all be present:
- First Name
- Last Name
- Email
- Phone
- Country
- ID Type
- ID Number
- TIN (Tax Identification Number)
- Date of Birth
- ID Expiry Date
- Street
- City
- State
- Zip Code
If any of these are missing, the request will fail and the response will tell you which fields are missing.TIN label lookupThe tin field is required for USD customers, but the actual identification type varies by country (e.g. SSN for US individuals, BVN for Nigerian individuals). See Understanding identification types for the full workflow, or call the Get identification type endpoint to look up the correct label before creating or updating the customer.ID must not be expiring soonThe customer’s identity document must have an expiry date at least one month from today.Valid postal codeThe customer’s zip code must be a valid postal code for their country. Managing Virtual Bank Accounts
Once created, you can manage your Virtual Bank Accounts using the following endpoints:
