Virtual bank accounts
Frequently asked questions about virtual bank accounts
Do we need to create a virtual bank account for each customer?
Yes. Every Virtual Bank Account must be linked to a verified customer. Each customer needs their own virtual account to ensure proper tracking of payments. You cannot create a Virtual Bank Account without providing a valid customer_id.
NGN Virtual Bank Accounts work for both type=individual and type=business customers — businesses must complete the KYB flow first. USD, GBP, and EUR Virtual Bank Accounts currently support type=individual only.
Can I create multiple virtual bank accounts for the same customer?
Not for the same currency and wallet. Each customer can only have one Virtual Bank Account per wallet and provider combination. If one already exists, the request will be rejected.
How do we create a virtual bank account?
- Create a customer and complete their verification.
- For
type=individual, follow the standard KYC flow (upload identity files via/files). - For
type=business, follow the KYB flow (owners + KYB documents +/submit).
- For
- Use the Create Virtual Bank Account endpoint with
wallet_idandcustomer_id.
If the customer flow requires a tin, get the correct label or field from the Get identification type endpoint before collecting it.
See the Virtual Bank Accounts guide for full prerequisites by currency.
Can I test virtual bank accounts in the development environment?
It depends on the currency. The development environment is https://api-dev.blaaiz.com.
| Currency | Account creation in development | Deposits settle in development |
|---|---|---|
| NGN | Yes | Yes |
| USD | Yes | No |
| GBP | On hold | No |
| EUR | On hold | No |
GBP and EUR account creation is on hold in the development environment. A GBP or EUR create request can return 400 with this message:
Failed to create virtual account. Please verify customer details and try again.
In the development environment, this message for GBP or EUR does not mean that the customer data is wrong. GBP and EUR virtual bank accounts work fully in production. To test them, do a controlled live test in production.
How do I do a controlled live test for GBP or EUR?
A controlled live test uses one real customer and one small real deposit in production. Use it only to test GBP and EUR virtual bank accounts.
Before you start, make sure that you have these items:
- Production credentials for
https://api-prod.blaaiz.com. - Production IP addresses that Blaaiz has whitelisted. See IP whitelisting.
- A GBP or EUR wallet on your business in production.
A controlled live test moves real money. Your normal fees apply to the deposit.
- Create one
type=individualcustomer in production with real details. - Upload the identity files of the customer.
- Wait for the
customer.verifiedwebhook. - Create a GBP or EUR virtual bank account for the customer.
- Wait for the
virtual_account.readywebhook. - Send a small real deposit to the account details in the webhook.
- Wait for the GBP or EUR collection webhook.
- Make sure that the deposit shows in the wallet balance.
If you get a virtual_account.failed or virtual_account.rejected webhook, read rejection_reason on the account. Send the account ID to support@blaaiz.com if the reason is not clear.
Which errors can the create request return?
The Virtual Bank Accounts guide lists the common errors, the HTTP status of each error, and the fix.
- A
403means that your business does not have the Create Virtual Account feature. It can also mean that your access token does not have thevirtual-account:createscope. - A
404means that the wallet does not belong to your business, or that you do not have a wallet in that currency. - A
400means that Blaaiz cannot create the account for this customer. The message tells you the cause.
Does a virtual bank account need more customer data than verification?
Yes. Verification checks the identity of the customer. Each currency also needs a set of fields on the customer before Blaaiz can create the account.
| Currency | Fields to check before you create the account |
|---|---|
| GBP, EUR | first_name, last_name, email, country, id_type, id_number, and dob, street, city, zip_code, and id_expiry_date in kyc_data |
| USD | All GBP fields, and phone, tin, and state in kyc_data |
GBP and EUR do not need a phone number. For USD, the meaning of tin depends on the country of the customer. For example, tin is the Bank Verification Number (BVN) for a Nigerian individual. Use Get identification type to get the correct label.
If a field is missing, the create request returns 400. The message starts with Cannot process and lists the missing fields. The Virtual Bank Accounts guide shows the full rules for each currency.
To add a missing field to a VERIFIED customer:
- Send the missing fields in
PUT /api/external/customer/{id}. - Send the create request again.
On a VERIFIED customer, PUT sets only the fields that are empty. Blaaiz does not change a field that already has a value. You cannot update a customer while verification is in progress.
Is there a country restriction for GBP, EUR, or USD virtual bank accounts?
Blaaiz does not restrict GBP, EUR, or USD virtual bank accounts by the country of residence of the customer. For example, a Nigerian resident with a passport passes the Blaaiz checks for GBP and USD.
The customer data must still pass the checks for the currency. For example, zip_code must be a valid postal code for the country of the customer.
The bank partner that issues the account does its own checks. Because of these checks, an account can stay PENDING for more time, or end as FAILED or REJECTED. Read rejection_reason on the account to find the reason.
What must my business have before I create a virtual bank account?
Your business needs these items. No other setup is necessary.
| Requirement | Response if the requirement is missing |
|---|---|
| The Create Virtual Account feature on your business | 403 with The Create Virtual Account feature is not enabled for this business. |
The virtual-account:create scope on your access token | 403 |
| A wallet in the currency of the account | 404 with Please create a wallet in this currency first. |
A VERIFIED customer that belongs to your business | 400 with a message about the customer |
A wallet does not need an existing virtual bank account before you create one.
Why does the list of virtual bank accounts for my wallet return no accounts?
GET /api/external/virtual-bank-account?wallet_id={id} returns the virtual bank accounts that you created for your customers on that wallet. The list stays empty until Blaaiz creates the first account on the wallet. A create request that fails does not add an account to the list.
If the wallet does not belong to your business, the request returns 404 with Wallet not found.
Can business customers get GBP, EUR, or USD virtual bank accounts?
Not now. GBP, EUR, and USD virtual bank accounts are available only for type=individual customers. The API rejects a type=business customer for these currencies with 400. This rule applies to all business customers, including customers on kyb_scope=FULL.
NGN virtual bank accounts are available for verified business customers on kyb_scope=MINIMAL and kyb_scope=FULL. Check the changelog for changes to this rule.
To collect CAD for business customers, see Can I use Interac auto-deposit for my business customers?