Virtual Bank Accounts
How to create and manage Virtual Bank Accounts for receiving payments
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.
Customer type restrictions by currency. NGN Virtual Bank Accounts work for both type=individual and type=business customers (Minimal and Full). GBP, EUR, and USD Virtual Bank Accounts require either type=individual (verified) or type=business with kyb_scope=FULL — kyb_scope=MINIMAL is NGN-only. Business customers must complete the KYB flow (/submit) before the customer is VERIFIED.
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 |
How to use this in your integration:
- Call Get identification type with the customer's
countryandtype(or theircustomer_idif you already have one). - Use the returned
labelto 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
tinfield 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
countrymust match the identity document submitted for KYC. - How long does customer verification take? See the warning below.
Verification is not instant. After you upload identity documents for a customer, those documents go through a review process. The customer's status will remain PENDING (or, for business customers after /submit, PROCESSING) until that review is complete.
For individual customers, the review finishes within a few minutes in most cases; up to 2 hours under additional screening. Do not raise support tickets within that window. Escalate to support@blaaiz.com only if verification has been pending for 5 hours or more.
For business customers, business KYB review typically takes 1–5 business days. Do not raise tickets within that window. Escalate only if the customer has been PROCESSING for more than 5 business days. See Business customer KYB.
Listen for the customer.verified or customer.rejected webhook to know when the review is complete.
- How do I know the correct
tinlabel 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.
Wallet must exist
You must have a wallet in the currency you want to create a Virtual Bank Account for. Pass a valid wallet_id in your request.
Customer is always required
You must provide a customer_id for all currencies. The customer must belong to your business and must have verification_status of VERIFIED before you can create a Virtual Bank Account. For NGN, both type=individual (verified through KYC) and type=business (verified through the KYB flow) are accepted. For GBP, USD, and EUR, only type=individual is supported.
No duplicate accounts
You 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 match
The customer's country must match the country on the identity document submitted for KYC.
Accepted identity documents
Only a Driver's License, Passport, or Resident Permit is accepted for individual customers. Business customers identify via registration_number + incorporation_country and supply a Certificate of Incorporation (or equivalent formation document) through the KYB document collection. ID cards (National Identity Cards) are not accepted. No other document types are supported.
Document quality
All uploaded documents must be clear, legible, and authentic. Blurry, cropped, obscured, or otherwise unclear images will not be reviewed and will be rejected. Fraudulent or falsified documents will not be tolerated — repeated attempts to submit false or invalid documents will result in the customer being permanently blacklisted from the platform. There are no exceptions or compromises.
Customer is required
You must provide a customer_id. The customer must be verified and belong to your business.
Immediate activation
NGN Virtual Bank Accounts are typically activated immediately and the response will return with a SUCCESSFUL status along with the account details.
Customer is required
You must provide a customer_id. The customer must be verified and of type individual.
Customer information must be complete
The following fields must be present on the customer's profile and KYC data before creating a GBP Virtual Bank Account:
- First Name
- Last Name
- 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 format
The 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 format
The customer's street address must contain only alphanumeric characters and the following: - / # ( ) ' , .
ID must not be expiring soon
The customer's identity document must have an expiry date at least one month from today.
Valid postal code
The customer's zip code must be a valid postal code for their country.
Customer is required
You must provide a customer_id. The customer must be verified and of type individual.
Customer information must be complete
The following fields must be present on the customer's profile and KYC data before creating an EUR Virtual Bank Account:
- First Name
- Last Name
- 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 format
The 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 format
The customer's street address must contain only alphanumeric characters and the following: - / # ( ) ' , .
ID must not be expiring soon
The customer's identity document must have an expiry date at least one month from today.
Valid postal code
The customer's zip code must be a valid postal code for their country.
Customer is required
You must provide a customer_id. The customer must be verified and of type individual.
Identity document must be uploaded
The customer must have an identity document file uploaded before you can create a USD Virtual Bank Account.
Driver's License, Passport, or Resident Permit only
All individual customers must have a Driver's License, Passport, or Resident Permit as their identity document. ID cards (National Identity Cards) are not accepted. No other document types are accepted. All document images must be clear and legible — unclear images will be rejected. Repeated submission of fraudulent or invalid documents will result in the customer being permanently blacklisted.
Customer information must be complete
USD Virtual Bank Accounts require the most customer information. The following fields must all be present:
- First Name
- Last Name
- 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 lookup
The 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 soon
The customer's identity document must have an expiry date at least one month from today.
Valid postal code
The 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:
- List Virtual Bank Accounts — retrieve all Virtual Bank Accounts for your business.
- Get Virtual Bank Account — retrieve details of a specific Virtual Bank Account by ID.
- Close Virtual Bank Account — close a Virtual Bank Account that is no longer needed.