Create a Payout

Creates a Payout in pending_approval. Idempotent on (Business, environment, idempotency_key) within 24h — a duplicate within the window returns the original Payout with HTTP 200. In sandbox the Business must have a funded sandbox wallet: an empty (or unprovisioned) one is refused with SANDBOX_WALLET_UNFUNDED (422) before anything is written, and completing the business profile funds it with test money.

POST /v1/payouts

Create a Payout Intent

cURL

curl --request POST \
  --url https://api.example.com/v1/payouts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "beneficiary_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "bank_account_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "amount_minor": 123,
  "currency": "<string>",
  "idempotency_key": "<string>",
  "external_ref": "<string>",
  "validator_strategy": "manual",
  "replaces_payout_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "via": {}
}
'

201

{
  "payout": {
    "id": "<string>",
    "state": "pending_approval",
    "beneficiary_id": "<string>",
    "bank_account_id": "<string>",
    "amount_minor": 123,
    "purpose_of_payment": "advertising",
    "currency": "<string>",
    "external_ref": {},
    "idempotency_key": "<string>",
    "validator_strategy": "manual",
    "environment": "sandbox",
    "provider": {},
    "provider_payout_id": {},
    "rail_ref": {},
    "replaces_payout_id": {},
    "created_at": "2023-11-07T05:31:56Z",
    "beneficiary_name": {},
    "beneficiary_type": "person",
    "via": {}
  }
}

Authorizations

Authorization · string · header · required

Cleff API key issued to a Business that self-registers via POST /v1/registration

Body

application/json

beneficiary_id · string<uuid> · required

bank_account_id · string<uuid> · required

Destination BankAccount for this disbursement. Must belong to the targeted Beneficiary and be in verified status.

amount_minor · number · required

Amount in minor units (e.g. cents). Max 9007199254740991 (2^53−1) to preserve JS integer precision.

Required range: x <= 9007199254740991

currency · string · required

ISO 4217 currency code

idempotency_key · string · required

Caller-supplied idempotency key, scoped to (Business, environment); 24h short-circuit window.

purpose_of_payment · enum<string> · required

Why the funds are being sent. Routefusion requires a purpose-of-payment on every transfer. Provisional corridor-agnostic set; coded values live behind the purpose-of-payment seam.

Available options: advertising, advisor_fees, charity, education, family_support, investment, loan_repayment, medical, other, payroll, purchase_of_goods, purchase_of_services, real_estate, royalties, taxes, treasury, travel

external_ref · string

Business-supplied reference (e.g. tradeId/jobId).

validator_strategy · enum<string>

Override the per-Business default validator strategy for this Intent.

Available options: manual

replaces_payout_id · string<uuid>

Self-link to a previously-failed Payout this Intent is replacing. The predecessor must be in failed state, belong to the same Business, and not have been replaced already.

via · object

Channel metadata. Server infers a default from the auth source (session→dashboard, API key→api). Clients may declare { channel: 'sdk', sdkVersion? } or { channel: 'cli', cliVersion? }; other channels are rejected.

Response

201

application/json

payout · object · required

Show child attributes