Virtual Accounts Solution Cheatsheet

Async account creation, strict Settlement -> Parent -> Sub routing, and customer-facing account numbers for direct deposits without losing operational control.

Choose Your Perspective

👨‍💻

For Developers

Simple Account Creation

Queue virtual account creation via API, monitor the job, then use the resulting account number for deposits

Comprehensive API Coverage

Create/list/update virtual accounts; monitor jobs; list transactions and deposits; settlement and withdrawal flows

Developer-Friendly

OpenAPI specs, UAT & production environments, comprehensive documentation

Integration Support

Postman collections, code samples, and dedicated API support

Common Transaction Flows

Transaction Steps

Submit POST /v1/virtual-accounts for the customer

Poll the background job until the item result succeeds

Read the resulting virtualAccountNumber and bicCode

Customer deposits into the dedicated sub account

UAT Starter Pack

🚀

First Successful Integration

Start with the exact UAT flow: create, poll, read job results, list accounts, and patch clientReference.

🧭

Allowed API Flows

Use the flow matrix before attempting any internal or external money movement.

🛠️

Troubleshooting

Diagnose `202 Pending`, `CompletedWithErrors`, unsupported transfers, and account-category confusion.

🧪

UAT Limitations

Check sandbox-specific setup rules, API-vs-portal guidance, and how temporary issues should be published.

Canonical API Calls

Create VA Job

POST /v1/virtual-accounts

Queue a virtual account create request in a provisioned currency

Request

curl -X POST https://api-uat.bcb.bm/v1/virtual-accounts \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "items": [
      {
        "currency": "USD",
        "accountHolderName": "Jane Smith",
        "accountName": "Jane Smith",
        "clientReference": "USER-12345"
      }
    ]
  }'

💡

Authentication: All API calls require a valid JWT token from /auth/token. For UAT, use https://api-uat.bcb.bm. Virtual account creation is asynchronous, so always follow the initial create response with the jobs endpoints before treating an account as created.

🚀 VAS UAT quickstart 🛠️ Troubleshooting 📮 Import to Postman 📄 Download OpenAPI Spec

Practical Guardrails

⏳

Async Create Workflow

`POST /v1/virtual-accounts` returns a background job. Do not treat the account as created until the item result succeeds.

🌍

Provisioning Is Per Currency

Each currency needs both a Settlement Account and a Parent Account before virtual account creation will succeed.

🔀

Supported Paths Only

Sub -> Sub is not a valid VAS flow. Keep every supported money movement inside the approved hierarchy.

✅

Same-Name Controls

External withdrawals and inbound funding still need same-name and source-of-funds controls.

📡

API Is Source Of Truth

In UAT, verify create, patch, and list behavior through the API when the portal UI and API do not agree.