Skip to main content
POST
/
payouts
Create a payout
curl --request POST \
  --url https://api.conduit.financial/v2/payouts \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "customerId": "<string>",
  "assetAmount": {
    "amount": "<string>",
    "chain": "<string>"
  },
  "destination": {
    "recipient": {
      "rail": "US",
      "accountNumber": "<string>",
      "routingNumber": "<string>",
      "bankAddress": {
        "addressLine1": "<string>",
        "city": "<string>",
        "country": "<string>",
        "addressLine2": "<string>",
        "state": "<string>",
        "postalCode": "<string>"
      },
      "phone": "<string>",
      "type": "INDIVIDUAL",
      "firstName": "<string>",
      "lastName": "<string>",
      "postalAddress": {
        "addressLine1": "<string>",
        "city": "<string>",
        "country": "<string>",
        "addressLine2": "<string>",
        "state": "<string>",
        "postalCode": "<string>"
      },
      "bankName": "<string>",
      "dateOfBirth": "2023-12-25",
      "countryOfCitizenship": "<string>"
    },
    "type": "crypto"
  },
  "clientReferenceId": "<string>",
  "documents": [
    "<string>"
  ]
}
'
{
  "id": "<string>",
  "customerId": "<string>",
  "source": {
    "type": "wallet",
    "walletId": "<string>",
    "address": "<string>",
    "assetAmount": {
      "code": "USDC",
      "chain": "ethereum",
      "amount": "100"
    }
  },
  "destination": {
    "type": "wallet",
    "walletId": "<string>",
    "address": "<string>",
    "assetAmount": {
      "code": "USDC",
      "chain": "ethereum",
      "amount": "100"
    }
  },
  "fees": [
    {
      "code": "FIXED_FEE",
      "type": "fixed",
      "assetAmount": {
        "code": "USDC",
        "chain": "ethereum",
        "amount": "100"
      }
    }
  ],
  "createdAt": "2026-01-15T09:30:00.000Z",
  "type": "withdrawal",
  "requiresUserSignature": true,
  "customerName": "<string>",
  "clientReferenceId": "<string>",
  "completedAt": "2026-01-15T09:30:00.000Z",
  "failureMessage": "<string>",
  "cancelledAt": "2026-01-15T09:30:00.000Z",
  "linkedOrderId": "<string>",
  "queuePosition": 4503599627370495
}

Authorizations

​
x-api-key
string
header
required

Headers

​
Idempotency-Key
string
required

Caller-generated unique key that lets the server safely replay this request. The cached response is returned for 5 minutes on any retry with the same key from the same API principal. Required on every state-changing money-moving or resource-creating POST.

Required string length: 1 - 128
Pattern: ^[A-Za-z0-9_.:-]{1,128}$

Body

application/json
​
customerId
string
required
​
assetAmount
object
required
​
destination
object
required
​
purpose
enum<string>
required

Declared business purpose of this payout. Drives documentation requirements and whitelist policy.

Available options:
INTERCOMPANY,
TREASURY_MANAGEMENT,
PAYMENT_FOR_GOODS_OR_SERVICES,
PAYROLL,
INVESTMENTS,
OTHER
​
clientReferenceId
string
Pattern: ^[A-Za-z0-9_\-:.]{1,255}$
​
documents
string[]

IDs of previously uploaded supporting documents (doc_*), must be uploaded with purpose transaction_support. Maximum 10.

Maximum array length: 10
Pattern: ^doc_[0-9A-Za-z]{22}$

Response

Client-facing view of an outbound withdrawal (debit out of a customer VA/wallet).

​
id
string
required
Pattern: ^txn_[0-9A-Za-z]{22}$
​
customerId
string
required
Pattern: ^cus_[0-9A-Za-z]{22}$
​
status
enum<string>
required
Available options:
pending,
processing,
completed,
failed,
cancelled
​
source
object
required

One side (source or destination) of a transaction. Discriminated by type.

​
destination
object
required

One side (source or destination) of a transaction. Discriminated by type.

​
fees
object[]
required
​
createdAt
string<date-time>
required

ISO 8601 timestamp

Example:

"2026-01-15T09:30:00.000Z"

​
type
enum<string>
required
Available options:
withdrawal
​
requiresUserSignature
boolean
required
​
customerName
string

Display name of the customer that owns the transaction: business legal name or individual full name. Omitted when no name is available — either the create path didn't join the customer (e.g. the create-payout response) or the customer's identity record hasn't resolved a name yet. Per the public omit-don't-null convention, absence is never surfaced as null.

​
clientReferenceId
string
Pattern: ^[A-Za-z0-9_\-:.]{1,255}$
​
completedAt
string<date-time>

ISO 8601 timestamp

Example:

"2026-01-15T09:30:00.000Z"

​
failureCode
enum<string>
Available options:
USER_SIGNATURE_TIMEOUT,
USER_SIGNATURE_DECLINED,
USER_SIGNATURE_REJECTED_BY_PROVIDER,
CRYPTO_WALLET_MISCONFIGURED,
COMPLIANCE_HOLD,
AML_REJECTED,
COMPLIANCE_REJECTED,
RETURNED_BY_SENDER,
RAIL_POLICY_REJECTED,
INSUFFICIENT_FUNDS_AT_SETTLE,
RAIL_UNAVAILABLE,
SENDER_INFO_TIMEOUT,
TRAVEL_RULE_REJECTED,
PROVIDER_REJECTED,
CHAIN_BROADCAST_FAILED,
ROSTER_CHANGED
​
failureMessage
string

Human-readable description of failureCode. Defaults to the public error catalog text for the code; sandbox-driven failures may carry the operator-supplied reason instead.

​
cancelledAt
string<date-time>

ISO-8601 timestamp when the transaction was cancelled. Present only on status: cancelled.

Example:

"2026-01-15T09:30:00.000Z"

​
cancellationReason
enum<string>

Machine-readable cancellation reason. client_cancelled when the client called POST /v2/payouts/:id/cancel; expired is reserved. Omitted on non-cancelled rows. Mirrors orders.cancellationReason.

Available options:
expired,
client_cancelled
​
linkedOrderId
string
Pattern: ^ord_[0-9A-Za-z]{22}$
​
purpose
enum<string>

The business purpose declared at payout creation. Drives compliance gating: INTERCOMPANY requires a whitelisted recipient; other values require supporting documentation.

Available options:
INTERCOMPANY,
TREASURY_MANAGEMENT,
PAYMENT_FOR_GOODS_OR_SERVICES,
PAYROLL,
INVESTMENTS,
OTHER
​
queuePosition
integer

Position in the per-(wallet, chain) signing queue. 0 = head of queue / signing now. Absent when the payout is not on the user-signature path or has reached a terminal status.

Required range: 0 <= x <= 9007199254740991