Lifecycle and Statuses
Complete status reference for virtual accounts and transfers. Use this page for event-driven processing, polling fallbacks, and reconciliation logic.
Account Statuses
A virtual account is provisioned asynchronously. After creation, the account may remain in PENDING until the banking network confirms it.
| Status | Terminal | Description |
|---|---|---|
PENDING | No | Account registration in progress with the bank |
ACTIVE | No | Account is live — can receive deposits and send transfers |
FAILED | Yes | Registration failed at the banking network |
INACTIVE | Yes | Account was deactivated |
Account State Transitions
PENDING
│
├──────────> ACTIVE
│ │
│ └──────────> INACTIVE
│
└──────────> FAILED
Monitor Accounts
-
Query:
GET /wallet/v1/accounts -
Query by ID:
GET /wallet/v1/accounts/{accountAnyId} -
Webhook:
VIRTUAL_ACCOUNT_STATUS_UPDATE— fires when account status changes (e.g. PENDING to ACTIVE)
Transfer Statuses
Transfers represent money movement in and out of virtual accounts. Deposits are detected automatically; withdrawals are initiated via the API.
| Status | Applies to | Description |
|---|---|---|
PENDING | Deposits and withdrawals | Transfer is being processed. This status is optional for deposits. |
COMPLETED | Deposits and withdrawals | Transfer succeeded and the funds are available to the recipient. A partial reversal keeps this status and lowers filledAmount; a total one moves the transfer to CANCELLED. |
CANCELLED | Deposits | The deposit was rejected before completion, or a completed deposit was manually returned. |
CANCELLED | Withdrawals | The withdrawal failed before completion or was reversed after completion. |
Deposit state transitions
[PENDING] ──> COMPLETED
[PENDING] ──> CANCELLED
[PENDING] ──> COMPLETED ──> CANCELLED
Brackets indicate that PENDING is optional for deposits. CANCELLED before completion means rejection; COMPLETED → CANCELLED means a manually requested return.
Withdrawal state transitions
PENDING ──> COMPLETED
PENDING ──> CANCELLED
PENDING ──> COMPLETED ──> CANCELLED
A CANCELLED status before completion is a failure. A CANCELLED status after completion is a network reversal of the full amount and supersedes the previous successful state.
Partial reversals
A reversal can return part of the amount. Each partial reversal lowers filledAmount by the reversed amount and leaves the transfer in COMPLETED; the transfer moves to CANCELLED only when the whole amount has been returned. So a COMPLETED transfer with filledAmount lower than amount is partially reversed, and the COMPLETED → CANCELLED step in the paths above may be the last of several partial reversals. Every reversal, partial or total, is notified through VIRTUAL_ACCOUNT_TRANSFER_REVERTED; VIRTUAL_ACCOUNT_TRANSFER_STATUS fires only for the final CANCELLED.
Monitor Transfers
- Webhook:
VIRTUAL_ACCOUNT_TRANSFER_STATUS— usetypeto distinguishDEPOSITfromWITHDRAW - Webhook:
VIRTUAL_ACCOUNT_TRANSFER_REVERTEDfor each reversal, partial or total - Query:
GET /wallet/v1/transfers - Query by ID:
GET /wallet/v1/transfers/{transferAnyId}
See Webhooks for configuration and payload details.
Timing Expectations
| Operation | Typical duration |
|---|---|
| Account creation (PENDING → ACTIVE) | Seconds to minutes (varies by country) |
| Deposit detection | Seconds after bank confirmation |
| Withdrawal (PENDING → COMPLETED) | Instant for most countries |
See Coverage for country-specific execution timing.
Updated 2 months ago