Transaction Lifecycle

Every transaction is a stateful workflow. This page lists the states, the happy path, the exception states, and the only signal that counts as final settlement.

Happy-path state arc

CREATED
  │
  ▼
QUOTE_ACCEPTED            ← you accepted the quote (rate + fees pinned)
  │
  ▼
COMPLIANCE_PENDING        ← KYB / sanctions / wallet screening running
  │
  ▼
COMPLIANCE_APPROVED
  │
  ▼
COLLECTION_PENDING        ← pay-in initiated (Open Banking / IBAN / instant rail)
  │
  ▼
COLLECTION_CONFIRMED      ← funds received
  │
  ▼
SETTLEMENT_PENDING        ← conversion + bridge starting
  │
  ▼
SETTLEMENT_PROCESSING
  │
  ▼
SETTLEMENT_COMPLETED   ◀── the single FINAL settlement signal
  │                       (delivered as the settlement.completed webhook)
  ▼
PAYOUT_PENDING → PAYOUT_PROCESSING → PAYOUT_COMPLETED

On TEST, this arc completes in seconds (providers are mocked). On LIVE, timing depends on the collection and payout rails for the corridor.

Exception / terminal states

State	Meaning
COMPLIANCE_REJECTED	A compliance check failed; no money moves.
REQUIRES_MANUAL_REVIEW	Parked for human review (e.g. ambiguous screening result).
FAILED	The workflow failed after the money-moving threshold. Reconciliation decides if a reversal is needed.
CANCELLED	Cancelled before money movement.
REVERSED	A previously committed movement was reversed as a correction.

Important rules

• Never skip states. Transitions are explicit and validated. You cannot jump from CREATED to SETTLEMENT_COMPLETED.
• SETTLEMENT_COMPLETED is the only final settlement signal. Do not infer finality from a raw provider response, an email, or an on-chain transaction hash. The platform only reaches SETTLEMENT_COMPLETED after the validated workflow completes.
• Provider status ≠ settlement status. A provider reporting "success" is one input; the platform's state is the truth you should act on and display.
• Idempotent callbacks. Webhook deliveries and provider callbacks are idempotent — make your receiver idempotent too (key on the event id).

Polling vs webhooks

You can poll GET /v1/transactions/:id, but the recommended pattern is to subscribe to Webhooks and react to settlement.completed, settlement.failed, and the KYB events. Treat polling as a fallback.

Next

• Settlement flow
• Transactions reference