Transaction States

Verto reports progress through a state field on the resource and through webhook events. This page is the canonical list for both. Where a guide shows its own state table, that table is a subset of what is here.

Three naming conventions are in use, and they refer to the same lifecycles:

Surface	Convention	Example
FX trade `state`	camelCase	`inwardSettlementDone`
Payment `state`	SCREAMING_SNAKE	`COMPLETED`
Webhook `state`	lowercase	`completed`

Compare them case-insensitively rather than by exact string.

FX trade lifecycle

Returned as state on Create FX trade and Get FX trade details.

stateDiagram-v2
    [*] --> initiated
    initiated --> confirmed: rate booked
    confirmed --> inwardSettlementDone: funds received, FX leg settled
    inwardSettlementDone --> outwardSettlementDone: funds delivered
    confirmed --> archived: rate window expired unfunded
    outwardSettlementDone --> [*]
    archived --> [*]

`state`	Meaning
`initiated`	Trade created, not yet booked against a rate.
`confirmed`	Trade booked. For Fund Later and Held Rate, Verto is awaiting your funds.
`inwardSettlementDone`	Funds received and the FX leg has settled.
`outwardSettlementDone`	Converted funds delivered to the target wallet or beneficiary. Terminal.
`archived`	Trade cancelled, or the rate window expired before funding. Terminal.

⚠️
Two mismatches between the guides and the Exchange specification are unresolved, and are with the API team:

refunded appears in the state table on the Instant Settlement, Held Rate and Firm Order guides, but is not a member of the EOrderState enum.

initiated is in the enum but appears on none of those guides.

The legacy `transactionState` field

Older responses also carry transactionState, in snake_case. It is coarser than state:

`transactionState`	Closest `state`
`inward_remittance_pending`	`confirmed`
`inward_remittance_confirmed`	`inwardSettlementDone`
`outward_remittance_complete`	`outwardSettlementDone`

Prefer state for new integrations.

Payment lifecycle

Returned as state on Create a payment request and Get payment by ID.

`state`	Meaning
`REQUESTED`	Payment accepted and queued for processing.
`SCHEDULED`	Payment accepted for a future date, via `scheduledDate`.
`COMPLETED`	Funds delivered to the destination. Terminal.
`REFUNDED`	Payment returned and funds credited back. Terminal.
`CANCELLED`	Payment stopped before execution. Terminal.
`ARCHIVED`	Payment closed without completing. Terminal.
`DISPUTED`	Payment is under dispute or investigation.

📘
The permitted transitions between these states are not yet published — only the states themselves are defined in the Payment specification. Drive your integration off webhook events and a follow-up read rather than assuming an order.

Webhook events

Event	`eventType`	Announces
IBAN to wallet	`iban_to_wallet`	`requested`, `completed`, `disputed`, `archived`
Wallet to account	`wallet_to_account`	`requested`, `completed`, `refunded`, `archived`
Wallet to wallet	`wallet_to_wallet`	`completed`
Wallet credit	`wallet.credit.success`	Funds credited to a wallet
Statement ready	`statement.ready`	A requested wallet statement is available
Refund completed	`refund.completed`	A refund has settled

Two envelope shapes are in circulation — iban_to_wallet events are flat with createdDate, while wallet.credit.success is nested with createdAt and an event object. Verify against the event you are handling. Which shape is canonical is with the API team.

Verifying webhook signatures — confirm an event is genuinely from Verto before acting on it.
FX quote and book — the flows that produce these trade states.

FX trade lifecycle

The legacy transactionState field

Payment lifecycle

Webhook events

Related

The legacy `transactionState` field