The money lifecycle

Intents

Every call that moves money creates an intent: a durable record of what you asked for, what happened, and how far it got. POST /deposits, POST /withdrawals, POST /conversions and POST /payouts each create one. Your Idempotency-Key claims exactly one intent, forever. Read it back at any time with GET /deposits/{id}, GET /withdrawals/{id}, GET /conversions/{id} or GET /payouts/{id}.

The six states are named for what happened to your money, not for a pipeline stage. The same six apply to all four flows. A payout's states are named the same way, but read PROCESSING rather than EXECUTING_ONCHAIN: a payout runs on a fiat rail, not a chain, so a state name that implied one would be a lie. See Payouts below for its own ladder, including the RETURNED case that has no counterpart on the other three flows.

Three of them are terminal: SETTLED, FAILED and COMPENSATED.

Each ladder below reads top to bottom, and every arrow is coloured by where it lands: blue for in flight, green for settled, red for a failure where nothing moved, amber for a compensable one. Compare the four and the differences are the whole point of this page.

Deposits

Withdrawals

A withdrawal walks the same six states, with one difference.

A withdrawal that has started executing can never be declared FAILED. Every failure after that point lands FAILED_PENDING_COMPENSATION. Only a PENDING withdrawal, where nothing was ever attempted, reaches FAILED.

Build for this. An integration that treats "not settled and not pending" as "failed, so retry" will withdraw twice.

Conversions

A conversion walks the same six states, and reaches them the way a deposit does rather than the way a withdrawal does. The order record is written before anything executes, so its absence proves nothing moved. A conversion can therefore reach a terminal FAILED from EXECUTING_ONCHAIN.

Payouts

A payout's states carry the same meaning as the other three flows, presented under the wire names PROCESSING (in place of EXECUTING_ONCHAIN) and, on top, RETURNED — a state none of the other flows has, because none of them can be sent back by a receiving institution after settling.

A payout that reached the rail is declared FAILED only on the rail's own answer that it did not take the payment, never on inference. Anything short of that positive answer — a thrown submission, an unconfirmed acceptance — is FAILED_PENDING_COMPENSATION, not FAILED.

Which webhook fires when

Only terminal transitions are evented — two per flow, plus three for payouts: payout.returned, explained below, and the review pair payout.held and payout.released:

No event is sent for FAILED_PENDING_COMPENSATION or COMPENSATED. TCB resolves both states — automatically where the outcome can be proven, by an operator otherwise. Watch for them on the read endpoints instead.

payout.returned is the one event on this table that is not a terminal transition: it fires on an already-SETTLED payout moving to RETURNED, not on a state reaching its terminal one. A return can also arrive on a payout that is still PROCESSING; then payout.settled and payout.returned fire together, in that order, and the read shows RETURNED.

There is no transfer.failed. A within-tree transfer either commits, and the response says where the money is, or it never happened and you hold a 4xx. No third outcome exists, so do not wait for an event.

Event ordering is not guaranteed and neither is single delivery. Dedupe on the tcb-webhook-id header, and treat the read endpoint as the truth.

Settled, reserved, available

For each of your vault sub-accounts:

• settledShares — what the sub-account holds, the sum of its posted entries. A settled deposit adds; a settled withdrawal subtracts.
• reservedShares — shares held back because a withdrawal from this sub-account is in flight. Reserved at the moment the withdrawal is authorised, in the same transaction that claims the intent.
• availableShares — settledShares minus reservedShares. This is what a new withdrawal is checked against, and a request for more than this is refused with 400 INSUFFICIENT_SUB_ACCOUNT_POSITION before anything moves.

A reserve is released only by the settlement that also posts the withdrawal, in the same transaction.

Compensation

*_FAILED_PENDING_COMPENSATION means money moved on one leg and the other did not confirm. It states a real position. It is not a generic code for an unknown outcome.

What happens next:

1. TCB resolves it from the evidence. The record carries what the request path established, including the transaction receipt where one exists. Where that evidence proves the outcome, TCB completes the resolution automatically; otherwise an operator works it by hand. Nothing resolves one merely because time passed.
2. You will be told. Contact partners@threecomma.group if you are holding one and have not heard.
3. The intent stays readable. Poll GET /deposits/{id}, GET /withdrawals/{id}, GET /conversions/{id} or GET /payouts/{id}; the state moves to COMPENSATED when it is closed out.

For a payout, TCB resolves the compensable state from the rail's own answer about the payment: refunding where the rail holds no such payment or reports that it failed, completing forward where the rail holds it. Any other answer — including a payment the rail reports as already returned — is worked by an operator rather than resolved automatically.

On a withdrawal, COMPENSATED means the fiat you were owed reached you. It does not mean the withdrawal was reversed. The shares are already gone, so the resolution completes forward.

Three related codes mean something different. Do not confuse them with a compensable failure. DEPOSIT_SETTLEMENT_NOT_RECORDED, WITHDRAWAL_SETTLEMENT_NOT_RECORDED and CONVERSION_SETTLEMENT_NOT_RECORDED mean the money completed and only the bookkeeping is missing. Nothing is owed and nothing is in flight.

LEDGER_ENTRY_NOT_RECORDED also means the money completed, and it is the one code in this group that leaves something outstanding. The exact share movement could not be read back, so no ledger entry was posted and the intent stays EXECUTING_ONCHAIN instead of reaching a terminal state. On a withdrawal the reserve is still held, so that sub-account's availableShares stays reduced until an operator posts the entry. Contact TCB and quote the id.

All four codes carry the same instruction: poll the original key, and never resubmit under a new one.

Rail freeze

PARTNER_RAIL_FROZEN (409) means TCB's reconciliation found a share divergence on your position in a vault that it cannot explain, and has stopped the rail rather than move more money across it.

Idempotency across retries

On any timeout, dropped connection or 5xx, retry with the same Idempotency-Key. A new key on a retry path is a second money movement.

What each combination of key and parameters answers, how long a key is remembered, and which characters it may contain are in Conventions.

Pilot disclosure