Settlement Flow

This page describes how money moves end-to-end through Thiqwave. It maps the conceptual stages to the API calls and the events you will receive. No real funds move on TEST.

The canonical flow

 You (partner)                          Thiqwave                                Your payer / payee
 ─────────────                          ─────────                               ──────────────────

 1. POST /v1/customers      ──▶  Create + KYB the sender
 2. POST /v1/beneficiaries     ──▶  Attach a payout destination
 3. POST /v1/transactions/quote ──▶  Lock corridor + FX rate + fees   (TTL ~2 min)
 4. POST .../quote/:id/accept  ──▶  Accept the quote (rate locked)
 5. POST /v1/transactions      ──▶  Start settlement
                                       │
                                       ▼
                                 ┌────────────────────────────────────┐
                                  │  Collection   ← payer funds the pay-in      ◀── payer (IBAN / instant rail)
                                 │  Compliance   ← KYB / sanctions / wallet screen
                                 │  FX + Bridge  ← convert via the corridor
                                 │  Payout       ← deliver to beneficiary       ──▶  payee (bank account / wallet)
                                 └────────────────────────────────────┘
                                       │
                                       ▼  (events delivered to your webhook)
                                 settlement.created → on_ramp.completed
                                 → off_ramp.completed → settlement.completed

Stage-by-stage

#	Stage	What happens	API / Event
1	Create customer	The sender is created and run through KYB.	POST /v1/customers
2	Create beneficiary	A payout destination (bank/wallet) is attached to the customer.	POST /v1/beneficiaries
3	Request quote	Thiqwave returns a locked corridor + FX rate + fee breakdown with an expires_at.	POST /v1/transactions/quote
4	Accept quote	You accept within the TTL. The rate and fee config are pinned to the transaction.	POST /v1/transactions/quote/:id/accept
5	Create transaction	The money movement begins. Idempotency-Key required.	POST /v1/transactions → settlement.created
6	Collection	The pay-in is collected (virtual IBAN or instant rail depending on collection_method).	on_ramp.completed
7	Compliance	KYB, sanctions/PEP, and (for stablecoin legs) wallet screening run. Failures route to REQUIRES_MANUAL_REVIEW or FAILED.	(state transitions)
8	FX + bridge	The collected amount is converted across the corridor and bridged to the destination rail.	(state transitions)
9	Payout	Funds are delivered to the beneficiary's bank account or wallet.	off_ramp.completed
10	Settled	The transaction reaches the single final state.	settlement.completed

The four flow types

The same lifecycle supports four source/destination combinations:

Flow	Source	Destination	Example
Fiat → Fiat	Fiat (AED, …)	Fiat (supported corridors)	Classic cross-border remittance
Fiat → Stablecoin	Fiat (AED)	Stablecoin (USDT/USDC)	Treasury into a wallet
Stablecoin → Fiat	Stablecoin (USDC)	Fiat (supported corridors)	Off-ramp to a bank account
Stablecoin → Stablecoin	Stablecoin (USDT)	Stablecoin (USDC)	Wallet-to-wallet settlement

Two things to internalise

• Quote → Transaction is the only canonical path for production. A quote pins the corridor, FX rate, fee config, and payout route at acceptance time. There is no mid-transaction switching; failures route to FAILED or REQUIRES_MANUAL_REVIEW.
• Provider status is not settlement status. A raw provider "success" or a chain transaction hash does not mean the payment is final. Only SETTLEMENT_COMPLETED (delivered as settlement.completed) is the final signal. See Transaction lifecycle.

Idempotency and retries

Money-moving calls (POST /v1/transactions, POST /v1/payments) require an Idempotency-Key. Store the key before the first attempt; on a timeout or network error, retry the exact same call with the same key. See Idempotency & Rate Limits.

Next

• Transaction lifecycle
• Quickstart — run stages 1–5 on TEST.
• Webhooks — receive the stage events.