Money Movement Lifecycle

Money moves through Conduit in order. A customer funds a Virtual Account, the balance becomes available, you optionally convert it to another asset, you initiate a payout, and the payout’s transaction walks through a few states until it reaches a terminal one. Each step below answers the same four questions: what state you’re in, what you do to advance, what webhook fires, and what can go wrong. Conduit is submit-and-listen — you make one call and react to webhooks. You can poll the matching GET endpoint, but you should never have to. This guide is the map. It links down into the concept pages that own the authoritative field lists (Money, Virtual Accounts) and out to the endpoint reference (Payouts, Orders). It does not re-list them.

Test this flow in sandbox. Drive it end-to-end with simulated money and deterministic controls — start with the sandbox quickstart, then the sandbox overview for this flow, and the cheat sheet for every magic value and simulate endpoint.

Prerequisites

An onboarded customer. See Onboard a Customer.
A Virtual Account on that customer. See Add Virtual Accounts.
A webhook endpoint subscribed to the transaction.* and order.* events. See Webhooks.

The journey at a glance

Fund the Virtual Account        → deposit transaction: pending → completed
        │
        ▼
Balance becomes available       → balances[].available increases
        │
        ▼ (optional)
Convert the balance             → order: pending → succeeded
        │
        ▼
Initiate a payout               → payout transaction: pending → processing → completed
        │
        ▼
Terminal state                  → completed · failed · cancelled

Amounts everywhere in this journey use the one Money shape ({ "code": "USD", "amount": "100.00" }). Echo what Conduit sends you; never round-trip through a float.

Step 1 — Fund the Virtual Account

State: the account is active, balance is zero

You start with an active Virtual Account. You reached it by submitting a virtual_account feature application and receiving virtual_account.activated — see Add Virtual Accounts. A non-active account (pending_activation, disabled) cannot receive a usable deposit yet. The Virtual Accounts page covers that lifecycle.

Advance: send funds to the deposit instructions

Your customer sends funds to the depositInstructions[] returned on the Virtual Account. No API call starts a deposit. Conduit detects the incoming funds and opens a deposit transaction for you.

curl https://api.conduit.financial/v2/customers/{customerId}/virtual-accounts/{virtualAccountId} \
  -H "x-api-key: YOUR_API_KEY"

Webhooks: transaction.created, then transaction.completed

Conduit fires transaction.created with type: "deposit" when it detects the inbound funds, then transaction.completed once the deposit settles and the balance is credited. The public transaction status moves pending → completed.

A fiat deposit may be charged a fee. When it is, the deposit’s two side amounts differ: source.assetAmount is what the sender sent, and destination.assetAmount is what was credited to the Virtual Account. The difference is reported in fees[] — on GET /v2/transactions/{id} and on the transaction.completed payload. Post the destination amount to your own ledger and read the fee from fees; don’t subtract it a second time. fees is always present on both — a deposit charged nothing carries an empty array and its two amounts are equal.

On fiat deposits that arrived from an outside bank, the transaction’s source is external_bank_inbound and carries a sender block — name, country (ISO 3166-1 alpha-2), accountNumber, routingNumber, iban, bic — with what the sending bank transmitted; each field is present only when provided. A deposit delivered internally from another account in your own organization has no external sender: its source is internal_transfer, carrying originatingTransactionId (the payout that sent it) and no sender block — so branch on source.type rather than assuming every fiat deposit is external_bank_inbound. Amounts always live per-side (source.assetAmount / destination.assetAmount); transaction objects never carry a top-level assetAmount — only dedicated event payloads like transaction.awaiting_sender_information do.

A crypto deposit from an unregistered sender address parks at transaction.awaiting_sender_information instead of completing. The payload carries the sourceAddress and an expiresAt deadline. Register the sender before the deadline, or the deposit times out and fails with failureCode: sender_info_timeout. See SENDER_INFO_TIMEOUT.

What can go wrong

The deposit is reversed or compliance returns it before credit → transaction.failed with failureCode: returned_by_sender. See RETURNED_BY_SENDER.
A compliance review parks the deposit → transaction.failed with failureCode: compliance_hold. See COMPLIANCE_HOLD.
The sender address is unregistered → handled by the awaiting_sender_information path above; SENDER_INFO_TIMEOUT is the terminal failure if it expires.

Step 2 — The balance becomes available

State: funds are credited and spendable

Once transaction.completed fires for the deposit, the credited amount appears in the Virtual Account’s balances[].available. Each balance carries three buckets:

Bucket	Meaning
`available`	Spendable now — this is what a payout or conversion can draw on.
`pending`	Credited but not yet final; not spendable.
`frozen`	Held by a compliance action; not spendable.

Advance: read the balance

Read the Virtual Account and confirm available reflects the deposit before you spend it.

curl https://api.conduit.financial/v2/customers/{customerId}/virtual-accounts/{virtualAccountId} \
  -H "x-api-key: YOUR_API_KEY"

Spend against available only. Initiating a payout or order for more than the available amount is rejected at submission. The Virtual Accounts page is the source of truth for the balance shape.

What lands in available is the deposit’s destination.assetAmount, which is net of any deposit fee. If you size a wire to cover an order, send the order’s totalDebit plus the fee — wiring exactly totalDebit leaves the balance short and the order cannot execute.

Step 3 — Convert the balance (optional)

Skip this step to pay out in the same asset you hold. Convert when the balance and the payout currency differ — for example, USD in a Virtual Account that you want to send out as USDC. A conversion is an Order: a firm, rate-locked exchange.

State: pending, with a locked rate

POST /v2/orders creates the order in status pending and returns 202 Accepted. The response carries sourceAsset, destinationAsset (each { code, chain?, amount }), and a lockExpiresAt — the rate holds until then. First confirm the route is supported and learn any required recipient fields with GET /v2/orders/requirements.destination always identifies a managed resource ({ "type": "virtual_account", "id": "vac_..." } or { "type": "wallet", "id": "wlt_...", "asset": { "code": "USDC", "chain": "ethereum" } }), and so does source when you name one. lockSide picks which side amount is denominated in, and the order direction (onramp vs offramp) is inferred from the asset types — you don’t send a type.source is optional. This step assumes you already hold the balance, so it names one. To convert crypto that hasn’t arrived yet, omit source and send sourceAsset ({ "code": "USDC", "chain": "ethereum" }) instead — Conduit returns an address to fund the order at in depositInstructions, and the order executes itself once the funds clear. Those orders omit source from every response and carry caveats worth reading first: Deposit-Funded Orders.

curl https://api.conduit.financial/v2/orders \
  -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "idempotency-key: $(uuidgen)" \
  -H "content-type: application/json" \
  -d '{
    "source": { "type": "virtual_account", "id": "vac_..." },
    "destination": { "type": "wallet", "id": "wlt_...", "asset": { "code": "USDC", "chain": "ethereum" } },
    "lockSide": "source",
    "amount": "10000.00",
    "autoExecute": true
  }'

Advance: execute (or let it auto-execute)

A pending order does not move funds until executed, and creating it never checked whether the source was funded — that check only happens at execution. With autoExecute: true, Conduit automatically starts execution as soon as the available source balance covers totalDebit (principal plus fees, which can exceed the locked amount), with no client action required. Orders on the same source resource execute oldest-first, so a still-underfunded older order can block a newer, already-funded one until it’s funded, cancelled, or expires. Otherwise, call POST /v2/orders/:id/execute yourself: each call makes one immediate attempt, returning 422 INSUFFICIENT_FUNDS (order stays pending, unclaimed) if the balance is still short — fund the source and call it again. Either path must claim execution before lockExpiresAt or the order expires (see below); a manual /execute call also still works on an order created with autoExecute: true, so whichever reaches it first wins. To back out before execution, call POST /v2/orders/:id/cancel.

Webhooks: order.created → order.succeeded

order.created fires on creation. order.succeeded fires once the source amount is debited and the destination amount is credited and spendable. order.succeeded carries the spawned transactionId so you can reconcile against the underlying transaction. The order status moves pending → succeeded.

What can go wrong

No live rate for the pair at creation → POST /v2/orders returns RATE_UNAVAILABLE. See RATE_UNAVAILABLE.
The lock expires before the order is executed → the expiry sweep cancels it: order.cancelled with reason: expired. On a deposit-funded order this is the funding deadline passing unfunded, and any funds sent to its address afterwards go back to the sender with no event of their own.
The sourceAsset you asked to be funded in cannot fund an order this way → 400 UNSUPPORTED_ASSET.
Execution fails terminally → order.failed with a reasonCode: insufficient_funds (a rarer terminal path than the 422 above — e.g. a source deposit that later reversed after execution had already been claimed), provider_unavailable (transient — retry may succeed), provider_rejected (declined — change funding source or recipient), internal_error (contact support), or cancelled. This is distinct from a manual /execute call returning 422 INSUFFICIENT_FUNDS up front — that leaves the order pending and retryable, it is never a terminal order.failed.

Order-level failures surface on order.failed with a reasonCode. The transaction-level failureCode vocabulary in the next step is separate. Don’t expect a conversion failure on transaction.failed.

Step 4 — Initiate a payout

Now send the available balance out to a destination address. A payout is a withdrawal-type transaction. The POST /v2/payouts reference documents the request body and every field, and the Send a payout guide walks the full lifecycle. This section is about the states it passes through.

State: pending

POST /v2/payouts returns 202 Accepted with the transaction in status pending. While pending, the payout clears compliance and Travel Rule exchange, and — for non-custodial wallets — awaits the customer’s signature. The reserved balance is held but not yet sent.

curl https://api.conduit.financial/v2/payouts \
  -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "idempotency-key: $(uuidgen)" \
  -H "content-type: application/json" \
  -d '{
    "customerId": "cus_...",
    "virtualAccountId": "vac_...",
    "purpose": "treasury_management",
    "assetAmount": { "code": "USD", "amount": "1000.00" },
    "destination": { "type": "fiat", "rail": "fedwire", "recipient": { "...": "..." } },
    "documents": ["doc_..."]
  }'

Advance: usually nothing — Conduit drives it

A fiat payout advances on its own; a crypto payout first awaits the customer’s signature (below). You can still cancel a pending payout with POST /v2/payouts/:id/cancel until it broadcasts. Once it reaches processing, the cancel returns 409 PAYOUT_NOT_CANCELLABLE. Track state with GET /v2/payouts/:id (or the equivalent GET /v2/transactions/:id).

Webhooks: transaction.created (and signing events, if non-custodial)

transaction.created fires with type: "withdrawal". For a non-custodial wallet source, transaction.awaiting_signature then fires with the verificationUrl to route the customer to (that applies to a wallet in the passkey signing mode; a wallet in a programmatic signing mode instead carries a signingRequestId on that webhook — see Machine-signer stamping). Multi-signer payouts also emit transaction.signature_collected per stamp and transaction.quorum_met once enough are in. The Non-Custodial Wallets page covers that branch end to end.

What can go wrong while pending

The recipient isn’t whitelisted for an intercompany payout → 422 RECIPIENT_NOT_WHITELISTED at submission. See RECIPIENT_NOT_WHITELISTED.
A crypto destination address is malformed for its chain → 400 INVALID_ADDRESS_FORMAT at submission. See INVALID_ADDRESS_FORMAT.
A required supporting document is missing → 422 DOCUMENTATION_REQUIRED at submission. See DOCUMENTATION_REQUIRED.
The document review is declined after acceptance → transaction.rejected with reasonCategory: document_inadequate (the payout reads failed / failureCode: compliance_rejected).
The customer never signs or declines (non-custodial) → transaction.failed with user_signature_timeout or user_signature_declined. See USER_SIGNATURE_TIMEOUT, USER_SIGNATURE_DECLINED.

Step 5 — The payout reaches the rail

State: processing

Once compliance clears and any required signature is in, the payout hands off to the rail (bank or chain) and moves to processing. The funds are committed. The payout can no longer be cancelled.

Advance: wait for finality

Nothing to do here. The transaction stays processing until the rail confirms settlement or reports a failure. Some rails (e.g. wire transfers) legitimately sit here for days — the stage field on GET /v2/payouts/:id (and GET /v2/transactions/:id) tells you why: awaiting_signature, under_review, or settling. Poll if you aren’t relying on webhooks.

What can go wrong at the rail

The source is short at settlement → transaction.failed with insufficient_funds_at_settle. See INSUFFICIENT_FUNDS_AT_SETTLE.
The chosen rail isn’t available → rail_unavailable; a rail-policy rule blocks it → rail_policy_rejected. See RAIL_UNAVAILABLE, RAIL_POLICY_REJECTED.
A crypto broadcast is declined pre-broadcast → provider_rejected. See PROVIDER_REJECTED.
The counterparty VASP rejects the Travel Rule transfer → travel_rule_rejected. See TRAVEL_RULE_REJECTED.

Step 6 — Terminal state

The transaction stops at exactly one terminal state. This is where your integration takes its final action.

Terminal status	Webhook	Meaning
`completed`	`transaction.completed`	Funds reached the destination. The settlement reference (e.g. `fedwireImad`, `achTraceNumber`, `txHash`) is on the relevant `source`/`destination` side of the payload.
`failed`	`transaction.failed` (or `transaction.rejected` for a declined document review)	The payout could not complete. Reserved funds, if any, are released. Branch on `failureCode`; when it’s absent the cause isn’t actionable — contact support.
`cancelled`	`transaction.cancelled`	Intentionally terminated (you called cancel, or a lock expired). Not a failure — there is no `failureCode`. `cancellationReason` is `client_cancelled` or `expired`.

The customer-facing transaction status collapses to five values — pending, processing, completed, failed, cancelled. Compliance outcomes that look distinct internally all surface as failed on the public API, differentiated by failureCode. The full failure-code catalog and its per-code recovery steps live in the Errors reference.

A completed transfer can still come back. Rare, but real: the receiving bank can send a wire or ACH credit back days after it settled — for a deposit, the sender’s institution reverses it; for a payout, the recipient’s bank returns it. When that happens the transaction flips straight from completed to failed with failureCode: "returned_by_sender". For a returned payout, Conduit may issue a replacement payout; the replacement carries retryOf, the id of the payout it replaces. See RETURNED_BY_SENDER.

Reacting to the terminal event

completed — store the settlement reference for reconciliation. The journey is done.
failed with an actionable failureCode — follow the matching error playbook above; most resolve to “fix the input and submit a new payout with a fresh idempotency-key.”
failed with no failureCode — treat as terminal; contact support.
cancelled — no funds moved; reserved balance is back in available. Submit a new payout when ready.

Getting Started

How Conduit Works

Concepts

How-To Guides

Webhooks

Money Movement Lifecycle

Prerequisites

The journey at a glance

Step 1 — Fund the Virtual Account

Step 2 — The balance becomes available

Step 3 — Convert the balance (optional)

Step 4 — Initiate a payout

Step 5 — The payout reaches the rail

Step 6 — Terminal state

Reacting to the terminal event

​Prerequisites

​The journey at a glance

​Step 1 — Fund the Virtual Account

​Step 2 — The balance becomes available

​Step 3 — Convert the balance (optional)

​Step 4 — Initiate a payout

​Step 5 — The payout reaches the rail

​Step 6 — Terminal state

​Reacting to the terminal event

Prerequisites

The journey at a glance

Step 1 — Fund the Virtual Account

Step 2 — The balance becomes available

Step 3 — Convert the balance (optional)

Step 4 — Initiate a payout

Step 5 — The payout reaches the rail

Step 6 — Terminal state

Reacting to the terminal event