Payment lifecycle
A cross-border payment is three moves: local collection, internal settlement, local payout. You drive the first steps — quote and order — and observe the rest through order status and webhooks.
Settlement between corridors is handled for you. Your integration only touches the endpoints on each side — everything in between is observable but not driven by you.
The five states
Every payment moves through the same five stages. You act on the first two; the remaining three are handled internally and surfaced back to you.
Quote
Lock a rate + fees.
Order
Commit with a destination.
Collection
Funds collected locally.
Settlement
Handled internally.
Payout
Beneficiary paid locally.
Order states
An order is the unit you track end to end. It carries the payment from collection through payout and reports one status at a time.
| State | Meaning | Terminal? |
|---|---|---|
Pending | Waiting for origin funds to be collected locally before settlement can begin. | No |
Received | Origin funds have arrived for the order. | No |
Processing | The order is committed and moving through collection, settlement, or payout. | No |
Success | The beneficiary has been paid out locally. Nothing more happens. | Yes |
Failed | The order could not complete. Any collected funds are returned or refunded. | Yes |
Canceled | The order was canceled before payout. It will not progress further. | Yes |
This is the spine of the lifecycle. Settlement and payout report finer-grained intermediate states — Exchanging, WithdrawProcessing, the WaitingFor… family, and more. See Statuses for the full set; the API reference is authoritative for the exact payload of each state.
Deposit states
A deposit is how funds enter — a fiat reference or IBAN, or a crypto address. It reaches Received once the incoming transfer is confirmed.
| State | Meaning | Terminal? |
|---|---|---|
Pending | Deposit instructions issued; no incoming funds observed yet. | No |
Processing | Incoming funds detected and being confirmed. | No |
Received | Funds confirmed and available to settle the order. | No |
Success | The deposit is fully processed. Nothing more happens. | Yes |
Failed | The deposit could not be processed — for example, funds were returned. | Yes |
Canceled | The deposit was canceled. It will not progress further. | Yes |
Withdrawal states
A withdrawal is a standalone payout from an existing balance to a fiat or crypto destination.
| State | Meaning | Terminal? |
|---|---|---|
Pending | The withdrawal is accepted and queued for processing. | No |
Processing | The balance is debited and the payout is on its way to the destination. | No |
Success | The destination has been paid out locally. | Yes |
Failed | The payout could not complete. The debited amount is returned to the balance. | Yes |
Canceled | The withdrawal was canceled before delivery. It will not progress further. | Yes |
Withdrawals can also pass through approval and review states — Pending2FA, Compliance, Approved, and more. See Statuses for the full set.
Observing state
Two ways to follow a payment through its states. Poll the order on demand, or — recommended — subscribe to webhooks and react as each state change arrives.
curl https://api.virtuabroker.com/v1/orders/7KA9DP2X4F1B \ -H "Authorization: Bearer $VB_TOKEN"
Prefer webhooks over polling. Subscribe once and receive each event — order_status_updated, deposit_completed, withdrawal_completed, and the rest — as it happens, instead of repeatedly asking.