The Virtual Accounts Solution (VAS) lets a corporate client hold customer funds in dedicated sub accounts while keeping money movement inside a controlled hierarchy.
Every VAS setup is built around three account layers:
- Settlement Account: external-facing account for inbound and outbound cash movement
- Parent Account: internal routing layer for VAS controls and reconciliation
- Sub Account / Virtual Account: customer-specific account used for fund segregation
If you are implementing VAS for the first time, read these pages in order:
You can only create virtual accounts in currencies where your client already has both:
- a Settlement Account
- a Parent Account
If a currency is not provisioned, the create request may still be accepted as a background job, but the item result can fail with an error such as No parent account with matching currency found.
These are the supported VAS flow patterns:
| Flow | Supported | Notes |
|---|---|---|
| External bank -> Sub Account | Yes | Customer deposits into their dedicated virtual account |
| Settlement -> Parent -> Sub | Yes | Approved credit flow into a customer account |
| Sub -> Parent -> Settlement | Yes | Approved debit or consolidation flow |
| Sub -> same-name external beneficiary | Yes | Use the external withdrawal flow and enforce same-name controls |
| Settlement -> external counterparty | Yes | Settlement transfer on behalf of the customer or platform |
These flows are not supported in VAS:
| Flow | Supported | Why |
|---|---|---|
| Sub -> Sub | No | VAS is not a peer-to-peer transfer model between customer sub accounts |
| Settlement -> Sub direct bypassing Parent | No | The VAS hierarchy must be preserved |
| Sub -> Settlement direct bypassing Parent | No | The VAS hierarchy must be preserved |
| Third-party or joint-account funding that fails same-name controls | No | Same-name and source-of-funds controls still apply |
- Create accounts with
POST /v1/virtual-accounts - Monitor create jobs with
GET /v1/jobs/{jobId} - Read item outcomes with
GET /v1/jobs/{jobId}/results - List provisioned VAS accounts with
GET /v1/virtual-accounts - Update your own identifier with
PATCH /v1/virtual-accounts/{virtualAccountNumber} - Verify activity with:
GET /v1/virtual-accounts/{virtualAccountNumber}GET /v1/virtual-accounts/{virtualAccountNumber}/transactionsGET /v1/virtual-accounts/{virtualAccountNumber}/deposits
clientReference is the field you should use to store your own customer, wallet, or reconciliation identifier.
- You can set it during create.
- You can update it later with
PATCH /v1/virtual-accounts/{virtualAccountNumber}. - You do not need to recreate the virtual account just to change
clientReference.
If you display account numbers to end customers, you must take reasonable steps to ensure deposits and withdrawals are consistent with same-name requirements.
Read the full guidance here:
If the portal UI and API disagree in UAT, use the API as the source of truth and verify the account state with direct GET calls.