Create a payout

POST/api/v2/payouts

Creates a payout in status created. andThen runs approval, and then send-claim-link or pay, in the same request and fails with their codes. Needs payouts:write, plus payouts:approve when andThen is set.

Header Parameters

idempotency-key?maxLength(255)

Client-chosen key, 1 to 255 characters (a UUID is recommended). The same key on the same endpoint within 24 hours replays the stored response with Idempotent-Replayed: true.

Length1 <= length <= 255

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

customId?|

Your own key for the payout. Use it in place of the id wherever a payout is referenced. It stays taken after the payout is deleted.

description*maxLength(5000)

What the payout is for. Shown to the recipient. Can span several lines: a literal \n becomes a line break, and consecutive line breaks collapse into one.

Length1 <= length <= 5000

amount*MoneyInput

a string matching the pattern ^\d+(.\d{1,2})?$

Match^\d+(\.\d{1,2})?$

currency*string

Currency of amount and of the invoices.

Value in

"USD"
"EUR"
"CHF"
"GBP"

recipient*|

Who is paid, discriminated on type: an email recipient claims by link, a counterparty can also be paid directly.

tags?array<>

Your labels for the payout. Filter the list with ?tag=. Up to 20 tags of 1 to 100 characters.

Itemsitems <= 20

availableOn?|

A future UTC day before which the payout cannot be claimed or paid.

locked?boolean

true locks the payout: it refuses PATCH and dashboard edits. Default false.

andThen?|

Runs the later steps of the payout cycle in the same request, all or nothing. approve needs payouts:approve; the _pay variant also needs a counterparty recipient.

Response Body

`application/json`

curl -X POST "https://example.com/api/v2/payouts" \  -H "Content-Type: application/json" \  -d '{    "description": "string",    "amount": "string",    "currency": "USD",    "recipient": {      "type": "email",      "email": "string"    }  }'

{  "object": "payout",  "id": "payout_0e4ba886-0bfe-4b6a-ae2e-d6d9d135dd1e",  "customId": "campaign-42",  "description": "string",  "amount": "100.00",  "currency": "USD",  "recipient": {    "type": "email",    "email": "jane@example.com",    "phone": "string"  },  "status": "created",  "locked": true,  "availableOn": "2026-10-01",  "expiresAt": "2026-09-24T10:00:00.000Z",  "tags": [    "string"  ],  "paymentMethod": {    "type": "crypto",    "asset": "string",    "currency": "EUR"  },  "senderInvoiceUrl": "string",  "recipientInvoiceUrl": "string",  "recipientInvoiceSource": "self_billing",  "failureCode": "account_closed",  "failureReason": "string",  "approvedAt": "2026-09-24T10:00:00.000Z",  "claimLinkSentAt": "2026-09-24T10:00:00.000Z",  "requestedAt": "2026-09-24T10:00:00.000Z",  "completedAt": "2026-09-24T10:00:00.000Z",  "createdAt": "2026-09-24T10:00:00.000Z",  "updatedAt": "2026-09-24T10:00:00.000Z"}

Header Parameters

Request Body

Response Body

201application/json

400application/json

401application/json

403application/json

404application/json

409application/json

422application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`