Create a new payout

Creates a new payout to transfer funds to a payee using their default payment method. Supports both regular payouts and subaccount payouts (test entities only). **Request Body** | Field | Type | Required | Description | Validation Rules | |--------------------------------------|------|----------|-------------|-----------------| | `payee_id` | UUID | Yes | ID of the payee to receive funds. | Must be a valid UUID for an existing payee | | `amount_in_minor_units` | Integer | Yes | Amount in the smallest unit of the currency. For USD, this is cents (100 = $1.00). | Must be a positive whole number. | | `currency_code` | String | No | ISO 4217 currency code. Defaults to the source account's currency. | If supplied, must match a supported country and currency combination. | | `rail` | String | No | - For bank accounts: Options `instant_bank`, `same_day_ach`, `standard_ach`, or `wire` depending on routing number<br>- For cards: Only `instant_card` is supported | Must be one of the supported rails for the payee's payment method | | `subaccount_id` | UUID | No | ID of the subaccount to debit from (test entities only). When provided, the payout will be debited from the specified subaccount instead of the main account. | Must be a valid UUID for an existing subaccount belonging to the entity. Only available for sandbox/test entities. | | `override_default_payment_method_id` | UUID | No | ID of a specific verified payment method to use instead of the payee's default payment method. If provided, this verified payment method will be used to create the payout. | Must be a valid UUID for an existing verified payment method belonging to the payee. If `rail` is also provided, it must be supported by this payment method | | `payout_metadata` | Object | No | Arbitrary metadata as key-value pairs to store with the payout for your own reference. | Must be an object with string keys and string values. Maximum 50 keys, each key max 40 characters, each value max 500 characters, total size max 16KB. | | `auto_approve` | Boolean | No | If set to true, payout will automatically transition to approved state. | default: `false` | **Examples:** - For USD, `amount_in_minor_units: 1000` is 1000 cents = $10.00 - For USD, `amount_in_minor_units: 1250` is 1250 cents = $12.50 **Response Body** | Field | Type | Description | |-------|------|-------------| | `id` | UUID | Unique identifier for the payout. | | `payee_id` | UUID | ID of the payee receiving the funds. | | `subaccount_id` | UUID | ID of the subaccount this payout is attributed to. Null if attributed to main account. | | `status` | String | Current status of the payout (`created`, `canceled`, `approved`, `initiated`, `debited`, `settled`, `failed`) | | `amount_in_minor_units` | Integer | The payout amount in the smallest unit of the currency. For USD, cents (100 = $1.00). | | `amount_in_cents` | Integer | Deprecated alias for `amount_in_minor_units`. | | `currency_code` | String | ISO 4217 currency code of the source account. | | `country_code` | String | ISO 3166-1 alpha-2 country code of the source account. | | `rail` | String | Payment rail used | | `payout_metadata` | Object | Contains payment method details and payee information (sensitive data is masked) | | `transfer_details` | Object | Details of the transfer (provided after processing begins) | | `client_metadata` | Object | Arbitrary metadata as key-value pairs that were provided when creating the payout | | `created_at` | DateTime | Timestamp when the payout was created | | `updated_at` | DateTime | Timestamp when the payout was last updated | **Note:** Use `amount_in_minor_units` in request bodies. The `amount_in_cents` field is deprecated and retained in responses for backward compatibility. **Idempotency Key** You can include an `Idempotency-Key` header to ensure that duplicate requests are handled safely. When you retry a request with the same idempotency key: - **200 OK**: If a payout with the same idempotency key already exists and no further work is needed for this request, the existing payout is returned. - **201 Created**: If no payout exists with the provided idempotency key, a new payout is created. - With **`auto_approve=true`**, an idempotency match that is still **`CREATED`** continues approve→initiate (same as a fresh create+`auto_approve`). A match in **`CANCELED`** or **`FAILED`** returns **409**. **Success Responses** | Status Code | Description | |-------------|-------------| | 200 | OK — An existing payout with the provided idempotency key was found and returned (idempotency recovery / already-advanced replay) | | 201 | Created — The payout was created; with **`auto_approve`**, processing finished within this response for your request (**`status`** reflects the result). | | 202 | Accepted — The payout was created (and approved when **`auto_approve`** is true). **`status`** in the body may still change; poll **`GET /api/payouts/{id}`** until the payout reaches a terminal status. | | 207 | Multi-Status — Payout was created (or already existed as **`CREATED`**) but **approval** failed. The response includes the payout data and a **`warning`**. The payout remains **`CREATED`**. | **Error Responses** | Status Code | Error Code | Description | |-------------|------------|-------------| | 400 | VALIDATION_ERROR | The provided data failed validation | | 401 | AUTHENTICATION_ERROR | Authentication credentials are invalid or missing | | 403 | AUTHORIZATION_ERROR | You do not have permission to perform this action | | 404 | NOT_FOUND | The payee or payment method was not found | | 409 | IDEMPOTENCY_KEY_CONFLICT | Idempotency key matches an existing payout in a terminal failed or canceled state; use a new key | | 422 | INVALID_PAYMENT_DETAILS | The payment details are invalid or incomplete | | 503 | (see response body) | With **`auto_approve`**, the payout was created (and approved) but initiation hit a **transient error**. **Retry** the same create request after a short wait. The JSON body includes `error_code` and `message`. | **Auto-approve behavior** When **`auto_approve=true`**, the API creates the payout (or continues from an idempotent **`CREATED`** match) and continues approval and async initiation as far as this request allows. You may receive **201**, **202**, **207**, or **503** depending on outcome: - **201** / **202**: The payout id is always in the response. If you receive **202**, poll **`GET /api/payouts/{id}`** until **`status`** reaches a value you treat as final for your integration. - **207**: Creation succeeded but **approval** failed; read **`warning`** and **`status`** (still **`CREATED`**). Standalone approve returns **4xx** for the same approval failure. - **503**: Transient error while starting async initiation—**retry** the create; use the response **`message`** (and **`error_code`**) for support and automation.