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.

StatusTerminalDescription
PENDINGNoAccount registration in progress with the bank
ACTIVENoAccount is live — can receive deposits and send transfers
FAILEDYesRegistration failed at the banking network
INACTIVEYesAccount was deactivated

Account State Transitions

PENDING
    │
    ├──────────> ACTIVE
    │               │
    │               └──────────> INACTIVE
    │
    └──────────> FAILED

Monitor Accounts


Transfer Statuses

Transfers represent money movement in and out of virtual accounts. Deposits are detected automatically; withdrawals are initiated via the API.

StatusApplies toDescription
PENDINGDeposits and withdrawalsTransfer is being processed. This status is optional for deposits.
COMPLETEDDeposits and withdrawalsTransfer 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.
CANCELLEDDepositsThe deposit was rejected before completion, or a completed deposit was manually returned.
CANCELLEDWithdrawalsThe 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

See Webhooks for configuration and payload details.


Timing Expectations

OperationTypical duration
Account creation (PENDING → ACTIVE)Seconds to minutes (varies by country)
Deposit detectionSeconds after bank confirmation
Withdrawal (PENDING → COMPLETED)Instant for most countries

See Coverage for country-specific execution timing.


Did this page help you?