Send a payout

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

Overview

A payout is a client-initiated outbound transfer of funds out of a customer’s Conduit balance. Use POST /v2/payouts to initiate and GET /v2/payouts/:id to track. Those two endpoint pages are the authoritative field-level reference for every request and response field; this guide covers the lifecycle, signing, cancellation, and failure handling around them. Payouts are asynchronous. After submission the payout enters a pending state while compliance, Travel Rule exchange, and (for non-custodial wallets) co-signing complete. Subscribe to transaction.* webhooks for real-time state transitions.

Request body

A crypto payout (the source wallet defaults to the customer’s oldest active wallet on the assetAmount chain; pass sourceWalletId to spend from a specific one):

{
  "customerId": "cus_034A0gCCVsxdV2PjHLx9k1",
  "purpose": "treasury_management",
  "assetAmount": {
    "code": "USDC",
    "chain": "ethereum",
    "amount": "1000.000000"
  },
  "destination": {
    "type": "crypto",
    "recipient": {
      "rail": "crypto",
      "chain": "ethereum",
      "address": "0xRecipientAddress",
      "attestation": { "custody": "self" }
    }
  },
  "documents": ["doc_034A0gCCW6w2ubcipmRoY8"],
  "clientReferenceId": "client-payout-001"
}

To move crypto between two wallets of the same customer, send a wallet destination instead of a recipient. The transfer is a real on-chain send, so it settles like any other payout and the receiving wallet is credited when it confirms. It requires purpose: "intercompany", an assetAmount.chain, and a destination wallet that differs from the source. No registered address and no whitelist entry apply, because there is no counterparty:

{
  "customerId": "cus_034A0gCCVsxdV2PjHLx9k1",
  "sourceWalletId": "wlt_034A0gCCVs2WISC5kS1P58",
  "purpose": "intercompany",
  "assetAmount": {
    "code": "USDC",
    "chain": "ethereum",
    "amount": "1000.000000"
  },
  "destination": {
    "type": "wallet",
    "walletId": "wlt_3yLkG0nRc8wO5mM2qS4x9u",
    "remittance": { "reference": "Q3 desk rebalance" }
  }
}

A destination wallet that is not an active wallet of that customer on the asset’s chain returns 422 INVALID_TRANSFER_PAIR. A destination that names the same wallet as sourceWalletId returns 400 VALIDATION_ERROR; one that names the wallet the payout would otherwise pick as its source returns 422 INVALID_TRANSFER_PAIR. The optional remittance carries a reference and a description of your own. Both halves of the transfer read it back on remittance: the withdrawal that sends the funds, and the deposit that credits them. A fiat payout debits a USD virtual account and pays a bank recipient — set virtualAccountId and a destination.type: "fiat" with a rail (fedwire, rtp, fednow, swift) and a recipient:

{
  "customerId": "cus_034A0gCCVsxdV2PjHLx9k1",
  "virtualAccountId": "vac_034A0gCCW1I7ZiTVLb0G7I",
  "purpose": "treasury_management",
  "assetAmount": { "code": "USD", "amount": "1000.00" },
  "destination": {
    "type": "fiat",
    "rail": "fedwire",
    "recipient": {
      "rail": "us",
      "type": "individual",
      "firstName": "Alice",
      "lastName": "Example",
      "accountNumber": "1234567890",
      "routingNumber": "021000021",
      "accountType": "checking",
      "phone": "+15551234567",
      "postalAddress": {
        "addressLine1": "1 Main St",
        "city": "New York",
        "state": "NY",
        "postalCode": "10001",
        "country": "USA"
      },
      "bankAddress": {
        "addressLine1": "100 Wall St",
        "city": "New York",
        "country": "USA"
      }
    }
  },
  "documents": ["doc_034A0gCCW6w2ubcipmRoY8"]
}

Every request field, its type, and whether it is required are documented on the POST /v2/payouts endpoint reference. Two fields carry integration meaning worth calling out here: purpose selects the compliance requirement the payout must satisfy (see Payout requirements), and documents is required for every purpose except intercompany (a whitelisted recipient substitutes) and, by default, prefunding — documentation policy can still require documents on a prefunding payout above a configured amount, so handle 422 DOCUMENTATION_REQUIRED there too. For a crypto payout, the destination address only has to be well-formed for its chain, and it must pass the chain’s own checksum where it has one: a mixed-case EVM address must carry a correct EIP-55 checksum, and a Stellar G... address must pass its StrKey checksum. A mistyped address returns 400 INVALID_ADDRESS_FORMAT. Any valid address is accepted as a destination.

Destination memo

Some chains carry a memo (also called a destination tag) alongside the payment. Exchanges and other custodians that hold many end users behind a single address use it to credit the right account. When your recipient gives you an address and a memo, send both — a payment that arrives at a shared address without its memo is credited to nobody, and recovering it depends on the custodian. Set it on destination.memo, in whichever of the two forms the recipient specifies:

"destination": {
  "type": "crypto",
  "memo": { "type": "text", "value": "user-4471" },
  "recipient": { "rail": "crypto", "chain": "stellar", "address": "GA5Z..." }
}

Field	Form
`text`	Up to 28 bytes of UTF-8. The limit is bytes, not characters, so accented or non-Latin characters cost more than one each.
`id`	An unsigned 64-bit integer, sent as a decimal string (`"0"` to `"18446744073709551615"`).

memo is optional and only accepted on chains whose payments carry one. Sending it on a chain that does not — any EVM chain, for example — returns 400 VALIDATION_ERROR rather than dropping the value silently.

Stellar destinations

A Stellar account has to be set up before it can receive USDC, and Conduit checks that when you create the payout rather than failing after the funds are reserved:

Response	What it means	What to do
`422 DESTINATION_NOT_ACTIVATED`	The account does not exist on the network. A Stellar account exists only once it holds a minimum XLM balance.	Ask the recipient to fund the account, then retry.
`422 DESTINATION_ASSET_NOT_ACCEPTED` (`details.reason: not_opted_in`)	The account exists but has not opted in to USDC.	Ask the recipient to add a USDC trustline, then retry.
`422 DESTINATION_ASSET_NOT_ACCEPTED` (`details.reason: frozen`)	The account has a USDC trustline, but the issuer revoked its authorization.	The recipient must resolve the freeze with the issuer, then retry.
`422 DESTINATION_ASSET_NOT_ACCEPTED` (`details.reason: limit`)	The trustline’s holding limit leaves no room for this amount.	Ask the recipient to raise the limit or free capacity, then retry.

Both are safe to retry unchanged once the recipient has acted — no transaction is created and no balance is reserved.

Payout requirements

purpose selects the requirement the payout must satisfy before it is accepted:

intercompany — the recipient must be whitelisted for this customer, otherwise 422 RECIPIENT_NOT_WHITELISTED. Register a bank recipient via whitelist recipients (it must reach registered), or a crypto address via registered addresses. Supporting documents are not required for this purpose.
prefunding — reserved for funding your own customers’ Conduit-issued accounts from a designated house account; the destination must resolve to one of your customers’ active issued accounts, otherwise a 422 PREFUNDING_* error. Supporting documents are not required by default; a documentation policy may require them above a configured amount.
Any other purpose — at least one supporting document is required, otherwise 422 DOCUMENTATION_REQUIRED (the response lists acceptedDocumentTypes). Upload each document with POST /v2/documents using purpose=transaction_support, then pass its doc_* id in documents. Document ids that don’t belong to your organization, or weren’t uploaded with purpose=transaction_support, return 400 DOCUMENT_IDS_NOT_FOUND. After acceptance the payout is held while the documents are reviewed; if the review is declined the payout ends as failed and a transaction.rejected webhook fires with reasonCategory: "document_inadequate".

The submitted documents are not echoed back on GET /v2/payouts/:id, and a payout held for document review reads as a normal pending (there is no distinct in-review status). If the review declines the payout, GET /v2/payouts/:id returns status: "failed" with failureCode: "compliance_rejected" and a failureMessage, and the transaction.rejected webhook carries reasonCategory + acceptedDocumentTypes.

Response

The response shape is the same for POST /v2/payouts and GET /v2/payouts/:id.

{
  "id": "txn_034A0gCCVmVhsfuR8SfVwM",
  "customerId": "cus_034A0gCCVsxdV2PjHLx9k1",
  "type": "withdrawal",
  "status": "pending",
  "clientReferenceId": "client-payout-001",
  "purpose": "treasury_management",
  "source": {
    "type": "wallet",
    "walletId": "wlt_034A0gCCVs2WISC5kS1P58",
    "address": "0xCustomerWalletAddress",
    "assetAmount": {
      "code": "USDC",
      "chain": "ethereum",
      "amount": "1000.000000"
    }
  },
  "destination": {
    "type": "external_crypto",
    "address": "0xRecipientAddress",
    "assetAmount": {
      "code": "USDC",
      "chain": "ethereum",
      "amount": "1000.000000"
    }
  },
  "fees": [],
  "createdAt": "2026-05-14T18:40:00.000Z"
}

Every response field is documented on the POST /v2/payouts and GET /v2/payouts/:id endpoint reference. Three of them need more than a field description to use correctly, so they have their own sections below: stage (see Progress: the stage field), failureCode (see Failures), and, for non-custodial payouts, requiresUserSignature and queuePosition (see Non-Custodial Crypto Withdrawals).

Progress: the `stage` field

While a payout is non-terminal (status: pending or processing), stage gives you a more specific progress signal than status alone — useful for rails that can legitimately take days to settle. stage is informational only. It does not replace requiresUserSignature, hasRfi, or failureCode for deciding whether your integration needs to act — use those fields for that, not stage.

Stage	Meaning	Customer action needed?
`awaiting_signature`	Waiting on the required transaction signature.	Yes — see `requiresUserSignature` and the `transaction.awaiting_signature` webhook.
`awaiting_customer_action`	Further input is needed from your customer.	Yes — details arrive on the matching event for your integration (e.g. `transaction.awaiting_sender_information`). This is not an RFI — `hasRfi` does not cover it.
`under_review`	Compliance, document, or verification review of something already submitted is in progress.	Usually no — check `hasRfi` and your document-request webhooks for whether a response is needed from you.
`settling`	Funds movement or settlement is in progress, or nothing is currently blocking the payout. No customer action is currently required.	No.
(omitted)	The payout has reached a terminal `status`.	Check `status`, `failureCode`, and `failureMessage`.

The set of stage values may grow over time as new progress states are added; treat stage as informational and handle an unrecognized value the same way you’d handle processing today.

Cancel a payout

POST /v2/payouts/:id/cancel

Cancel a payout before it broadcasts on-chain. The reserved balance is released back to the customer’s available balance and a transaction.cancelled webhook fires with cancellationReason: "client_cancelled".

curl -X POST {{api-host}}/v2/payouts/$PAYOUT_ID/cancel \
  -H "x-api-key: $API_KEY" \
  -H "idempotency-key: $(uuidgen)"

Headers:

Header	Required	Description
`x-api-key`	Yes	API key.
`idempotency-key`	Yes	UUID. Cancel is a money-adjacent operation; the header dedupes accidental retries.

Response: HTTP 200 with the payout in its current state. On success the cancel settles synchronously and status is cancelled, cancellationReason is client_cancelled, and cancelledAt is populated; failureCode and failureMessage are omitted (cancellation is not a failure). In the rare case the cancel needs more than ~5 seconds to settle (cold-start), the response still returns 200 but the payout may still show pending or processing — the cancel was accepted and the final state will follow shortly. Poll GET /v2/payouts/:id for the terminal state. To dedupe your own retry, reuse the same idempotency-key (cached for 5 minutes) — the same response you got the first time replays. With a fresh idempotency-key, a payout you previously cancelled returns 200 again with the same cancelled shape; a payout that failed for any other reason returns 409 PAYOUT_NOT_CANCELLABLE. Cancellable states:

Payout state	Behaviour
`pending` (pre-broadcast, including non-custodial payouts awaiting signature)	Cancels. Reserved balance is released. `status` becomes `cancelled` with `cancellationReason: "client_cancelled"`.
`processing` (broadcast already initiated)	`409 PAYOUT_NOT_CANCELLABLE`. The chain transfer cannot be unwound.
`completed`	`409 PAYOUT_NOT_CANCELLABLE`.
`cancelled` (from a prior cancel of this same payout)	200 — same `cancelled` shape as the first cancel.
`failed`	`409 PAYOUT_NOT_CANCELLABLE`. A genuinely failed payout cannot be cancelled.

Cancel is a state-based contract: any pending payout can be cancelled until funds reach the rail. The practical window varies by payout type. Non-custodial crypto payouts park at the cosign gate awaiting the customer’s signature, so they stay cancellable for the lifetime of that gate — long enough to script a cancel against them. Fiat payouts move through pending quickly and hand off to the rail inline once compliance clears, so by the time most integrators try to cancel they have already reached processing and return 409 PAYOUT_NOT_CANCELLABLE. A cancel issued early enough on a fiat payout can still succeed; the race is real but the window is narrow and not reliably scriptable. Errors:

Status	Code	Reason
`400`	`IDEMPOTENCY_KEY_REQUIRED` / `IDEMPOTENCY_KEY_INVALID`	Header missing or malformed.
`404`	`PAYOUT_NOT_FOUND`	No payout exists with this id for your organization.
`409`	`PAYOUT_NOT_CANCELLABLE`	The payout’s broadcast has begun, or it has reached a non-cancellable terminal state.
`409`	`PAYOUT_CANCEL_IN_PROGRESS`	The payout was just created and is not yet ready to accept the cancellation — a transient startup delay. The payout is still cancellable: retry after a brief delay.

Non-Custodial Crypto Withdrawals

When the source wallet is non-custodial, the payout requires the customer’s passkey approval before broadcast. Conduit cannot move a customer’s non-custodial funds without their co-signature.

How it works

POST /v2/payouts
       │
       ▼
 Compliance + Travel Rule (transparent — no client action needed)
       │
       ▼
 transaction.awaiting_signature webhook fired
       │
       ├── data.verificationUrl  ← route customer here
       └── data.expiresAt        ← sign before this time
       │
       ▼
 Customer visits /verify/<token> → passkey approval
       │
       ▼
 Broadcast → await finality → transaction.completed

Submit POST /v2/payouts as usual. If requiresUserSignature: true appears in the response, the payout is awaiting your customer’s signature.
The payout is screened for compliance and Travel Rule first. Once it clears, transaction.processing fires (its status becomes processing), then the transaction.awaiting_signature webhook fires when the payout is ready for the customer’s signature. Because screening runs before signing, a payout that fails compliance is rejected before this webhook is ever sent. The signature webhook carries verificationUrl + expiresAt on the payload itself.
Redirect the customer to the webhook’s verificationUrl before expiresAt. Use the expiresAt timestamp from the payload as the deadline — it can be up to 24 hours out; do not assume a fixed 15-minute window.
The customer approves with their passkey. Conduit broadcasts. transaction.completed fires when the chain confirms.

This describes a wallet in the passkey signing mode — human signers approve on the verify page, so the webhook carries a verificationUrl. A wallet in a programmatic signing mode receives a signingRequestId on the same transaction.awaiting_signature webhook — plus an optional verificationUrl when its roster has an active passkey signer who may also approve on the verify page; a machine integration reads the request via GET /v2/signing-requests/{signingRequestId} and resolves it via POST .../approve or .../reject. See Machine-signer stamping.

`POST /v2/payouts` — response (non-custodial)

The requiresUserSignature field is available immediately on the POST response: it’s true from creation until the payout’s signatures are collected (or it terminates) — including while the payout is still clearing compliance before signing, when it reports stage: "under_review" and the verify link does not yet exist. It flips to false once the signatures are in (during settlement, stage: "settling") or the payout reaches a terminal status (completed / failed). The verify URL + expiry are not part of the response shape — they arrive on the transaction.awaiting_signature webhook, which fires only after compliance + Travel Rule screening clears. So a true value does not always mean the customer can sign right now. transaction.processing is only a progress signal (screening cleared, the payout is queuing/preparing to sign) and does not carry a verify link — route the customer to sign only after transaction.awaiting_signature, which supplies verificationUrl and expiresAt.

{
  "id": "txn_034A0gCCVmVhsfuR8SfVwM",
  "customerId": "cus_034A0gCCVsxdV2PjHLx9k1",
  "type": "withdrawal",
  "status": "pending",
  "clientReferenceId": "client-payout-001",
  "purpose": "treasury_management",
  "source": {
    "type": "wallet",
    "walletId": "wlt_034A0gCCVs2WISC5kS1P58",
    "address": "0xCustomerWalletAddress",
    "assetAmount": {
      "code": "USDC",
      "chain": "ethereum",
      "amount": "1000.000000"
    }
  },
  "destination": {
    "type": "external_crypto",
    "address": "0xRecipientAddress",
    "assetAmount": {
      "code": "USDC",
      "chain": "ethereum",
      "amount": "1000.000000"
    }
  },
  "fees": [],
  "requiresUserSignature": true,
  "createdAt": "2026-05-14T18:40:00.000Z"
}

Field	Type	Description
`requiresUserSignature`	boolean	`true` for any non-terminal payout that will require the end-user’s signature — this includes payouts that are still waiting in the queue or collecting signatures, so it can be `true` before a signing link exists. It is NOT a signal that a link is ready to act on. Flips to `false` once `status` reaches `completed`, `failed`, or `cancelled`. Watch the `transaction.awaiting_signature` webhook for the actionable `verificationUrl` (the link to present to the user, with its expiry) — this 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) — and read `queuePosition` for the payout’s queue state. Available immediately on the POST response — use it to prepare your UX without waiting for the webhook.
`queuePosition`	number	The payout’s slot in the per-(wallet, chain) signing queue. Waiting payouts (queued behind a payout already in the signing step) expose this as a positive integer. The active payout (currently being signed) has the field absent from the response. Populated eventually — it may not appear on the initial `POST` response; check `GET /v2/payouts/:id` to observe the current value.

`GET /v2/payouts/:id` — response while awaiting signature

The signing step opens once the payout clears compliance and Travel Rule screening (those run before signing, so a compliance rejection stops the payout before any signature is requested). The verify URL + expiry are delivered on the transaction.awaiting_signature webhook, not on the GET response. The GET response continues to report requiresUserSignature: true while the payout is parked awaiting the customer’s signature:

{
  "id": "txn_034A0gCCVmVhsfuR8SfVwM",
  "customerId": "cus_034A0gCCVsxdV2PjHLx9k1",
  "type": "withdrawal",
  "status": "pending",
  "clientReferenceId": "client-payout-001",
  "purpose": "treasury_management",
  "source": {
    "type": "wallet",
    "walletId": "wlt_034A0gCCVs2WISC5kS1P58",
    "address": "0xCustomerWalletAddress",
    "assetAmount": {
      "code": "USDC",
      "chain": "ethereum",
      "amount": "1000.000000"
    }
  },
  "destination": {
    "type": "external_crypto",
    "address": "0xRecipientAddress",
    "assetAmount": {
      "code": "USDC",
      "chain": "ethereum",
      "amount": "1000.000000"
    }
  },
  "fees": [],
  "requiresUserSignature": true,
  "createdAt": "2026-05-14T18:40:00.000Z"
}

The verificationUrl + expiresAt arrive on the transaction.awaiting_signature webhook payload. expiresAt is an ISO 8601 UTC timestamp for the current signing attempt. If the signing window elapses before quorum, Conduit rebuilds the request with a fresh link and re-fires transaction.awaiting_signature with an incremented attempt. After the final rebuild attempt also elapses, the payout fails with failureCode: "user_signature_expired" and no funds are moved.

Webhook sequence

transaction.created
  ↓
transaction.awaiting_signature   ← route customer to verificationUrl
  ↓ (after customer approves; compliance + Travel Rule run, then chain confirms)
transaction.completed

If a signing window expires but rebuild attempts remain, a fresh link is issued:

transaction.awaiting_signature  (attempt: 1)
  ↓ (window expires, attempts remaining)
transaction.awaiting_signature  (attempt: 2)
  ↓ (all attempts exhausted or customer declines)
transaction.failed

See the Non-Custodial Wallets concept page for end-to-end flow detail, branding customization, and sandbox testing.

Failures

POST /v2/payouts returns synchronous errors only for validation and ID lookups. Once you receive 202 Accepted, the payout is in flight; most failures from that point arrive on the transaction.failed webhook. One exception: a payout declined at the document-review step (see Payout requirements) terminates on the transaction.rejected webhook instead — carrying reasonCategory + acceptedDocumentTypes — so subscribe to both. (GET /v2/payouts/:id then shows status: "failed" with failureCode: "compliance_rejected".)

Failure codes

When transaction.failed carries a failureCode, the failure has a known cause your integration can act on. Use the failureCode to decide what to show the customer and whether to retry.

Code	What happened	What to do
`user_signature_timeout`	The payout waited too long in the signing queue without reaching the signing step (queue max-residence timeout).	No funds were moved. Submit a new payout when the customer is ready to sign.
`user_signature_expired`	Every signing window was offered to the customer but quorum was not reached; all rebuild attempts were exhausted.	No funds were moved. Submit a new payout when the customer is ready to sign.
`user_signature_declined`	The customer declined the payout from the approval page.	No funds were moved. Submit a new payout if the decline was unintentional.
`user_signature_rejected_by_provider`	The customer’s passkey approval could not be accepted.	No funds were moved. Submit a new payout. If the same customer or wallet hits this repeatedly, contact support.
`crypto_wallet_misconfigured`	The wallet’s configuration prevents Conduit from moving funds from it.	No funds were moved. Conduit is investigating automatically. Contact support if the wallet is needed for a time-sensitive payout.
`travel_rule_rejected`	The counterparty VASP rejected the Travel Rule transfer before the on-chain broadcast.	No funds were moved. Confirm beneficiary details with the recipient and submit a new payout once the underlying issue has been addressed.

These failures land at HTTP semantic 422 (the asynchronous equivalent: the request was well-formed and accepted, but the payout could not be completed).

Failures without a `failureCode`

If transaction.failed arrives with no failureCode, the payout could not be completed and the cause is not something your integration can act on. Treat the transaction as terminal. Funds, if any were reserved, are released. Contact support if the customer needs help understanding why.

Getting Started

How Conduit Works

Concepts

How-To Guides

Webhooks

Overview

Request body

Destination memo

Stellar destinations

Payout requirements

Response

Progress: the `stage` field

Cancel a payout

Non-Custodial Crypto Withdrawals

How it works

`POST /v2/payouts` — response (non-custodial)

`GET /v2/payouts/:id` — response while awaiting signature

Webhook sequence

Failures

Failure codes

Failures without a `failureCode`

​Overview

​Request body

​Destination memo

​Stellar destinations

​Payout requirements

​Response

​Progress: the stage field

​Cancel a payout

​Non-Custodial Crypto Withdrawals

​How it works

​POST /v2/payouts — response (non-custodial)

​GET /v2/payouts/:id — response while awaiting signature

​Webhook sequence

​Failures

​Failure codes

​Failures without a failureCode

Overview

Request body

Destination memo

Stellar destinations

Payout requirements

Response

Progress: the `stage` field

Cancel a payout

Non-Custodial Crypto Withdrawals

How it works

`POST /v2/payouts` — response (non-custodial)

`GET /v2/payouts/:id` — response while awaiting signature

Webhook sequence

Failures

Failure codes

Failures without a `failureCode`