Virtual AccountsTransaction Types
Last updated 7 months ago
Transaction Types and Fund Flows
VAS does not permit arbitrary movement between any two accounts you can see in the same client profile. Supported flows are tightly constrained by the Settlement -> Parent -> Sub hierarchy.
Supported VAS flows
| Transaction Type | Direction | Supported | Notes |
|---|---|---|---|
| Deposit | External -> Sub | Yes | Customer deposits into the dedicated sub account |
ACRT - Authorized Credit Transfer | Settlement -> Parent -> Sub | Yes | Approved funding flow into a customer account |
ADBT - Authorized Debit Transfer | Sub -> Parent -> Settlement | Yes | Approved debit or consolidation flow out of a customer account |
OTWT - Withdrawal Transfer | Sub -> External | Yes | External withdrawal to the customer's same-name beneficiary account |
OTST - Settlement Transfer | Settlement -> External Counterparty | Yes | Payment or settlement flow from the settlement layer |
REVERSAL | Reject inbound | Yes | Reject or reverse unauthorized inbound funds |
Unsupported VAS flows
| Flow | Supported | Reason |
|---|---|---|
| Sub -> Sub | No | VAS does not allow direct virtual account to virtual account movement |
| Settlement -> Sub direct bypass | No | Parent layer must remain in the routing chain |
| Sub -> Settlement direct bypass | No | Parent layer must remain in the routing chain |
| Third-party or joint-account funding that fails same-name checks | No | Same-name controls still apply |
Important developer rule
The generic internal transfers API is not a free-form VAS transfer tool.
Before using any transfer endpoint with VAS accounts, confirm that the selected source and destination represent one of the supported flows above.
Flow details
Deposits (External -> Sub)
- A customer sends funds from an external bank account to the dedicated virtual account number.
- Deposits remain subject to same-name and source-of-funds controls.
- Use
GET /v1/virtual-accounts/{virtualAccountNumber}/depositsandGET /v1/virtual-accounts/{virtualAccountNumber}/transactionsto verify activity.
Authorized customer credit (Settlement -> Parent -> Sub)
- Corporate client initiates an approved credit flow.
- Funds move from Settlement to Parent and then into the selected Sub Account.
- This is the valid way to move funds down the hierarchy.
Authorized customer debit (Sub -> Parent -> Settlement)
- Corporate client initiates an approved debit flow.
- Funds move from the Sub Account back up through Parent to Settlement.
- This is the valid way to consolidate or settle funds out of a customer account.
Withdrawals (Sub -> External)
- Corporate client initiates an external withdrawal from the sub account.
- The beneficiary account must satisfy the same-name control requirements.
- The published endpoint for this flow is
POST /v1/virtual-accounts/{virtualAccountId}/withdrawals/external.
Settlement transfers (Settlement -> External Counterparty)
- Corporate client initiates the payment from the Settlement Account.
- Use the settlement layer for approved external counterparties and platform settlement obligations.
Common mistakes
- Mistake: "Both virtual accounts are in USD, so the transfer should work."
- Correction: Same currency is necessary, but not sufficient.
Sub -> Subis still unsupported.
- Correction: Same currency is necessary, but not sufficient.
- Mistake: "The account create call returned
202, so the account exists."- Correction: The account exists only after the background job finishes successfully.
- Mistake: "
GET /v1/virtual-accountsshould return only virtual accounts."- Correction: It returns settlement, parent, and sub accounts together. Filter by
category.
- Correction: It returns settlement, parent, and sub accounts together. Filter by
Related guides
Was this helpful?