---
title: "Create a headless payout"
method: POST
path: "/v1/headless_payout"
tags: ["Headless Payout"]
---

# Create a headless payout

`POST /v1/headless_payout`

Creates a payout for a KYC-verified customer in a single API call. Validates the customer has active TIER_2 KYC, creates or reuses an ACH bank account, and initiates the payout. Idempotent on clientReferenceId.

**Note:** This endpoint requires the customer to have been KYC-verified via the Headless KYC API. It is only available to merchants configured by the Breeze team. Please reach out to the Breeze team to find out more.

## Request body

- CreateHeadlessPayoutRequest — Headless payout details
  - `amount` integer, required
  - `currency` 'USD', required
  - `clientReferenceId` string, required
  - `releaseMethod` 'MANUAL' | 'AUTOMATIC', required
  - `customer` union, required
    - object
      - `id` string, required
      - `referenceId` string
      - `email` string, email, required
    - object
      - `id` string
      - `referenceId` string, required
      - `email` string, email, required
  - `bankAccount` object, required
    - `accountNumber` string, required
    - `routingNumber` string, required
    - `accountType` 'checking' | 'savings', required

## Response `200`

Success

- object — The created payout page in PROCESSING status
  - `status` 'SUCCEEDED', required
  - `data` CreateHeadlessPayoutResponse, required
    - `id` string, required
    - `status` 'CREATED' | 'PENDING' | 'PROCESSING' | 'PROCESSED' | 'ON_HOLD' | 'REFUNDED' | 'EXPIRED' | 'CANCELLED' | 'REJECTED', required
    - `amount` number, required
    - `fundingCurrency` 'USDC' | 'USDCE' | 'USDBC' | 'USDT' | 'EURC' | 'DAI' | 'BUSD' | 'BTC' | 'ETH' | 'BNB' | 'MATIC' | 'POL' | 'AVAX' | 'SOL' | 'TRX' | 'KAP' | 'ARB' | 'CBBTC' | 'PYUSD' | 'SNS' | 'HONEY', required
    - `payoutDestinationRail` 'ach' | 'sepa' | 'card_usd' | 'zengin' | 'twd_fisc' | 'hkd_fps' | 'krw_kftc'
    - `clientReferenceId` string, required
    - `releaseMethod` 'MANUAL' | 'AUTOMATIC', required
    - `merchant` object, required
      - `id` string, required
      - `livemode` boolean, required
    - `customer` object, required
      - `id` string
      - `referenceId` string
      - `email` string, required
    - `successReturnUrl` string
    - `failureReturnUrl` string
    - `url` string, required
    - `pendingStatus` 'PENDING_USER_CONFIRMATION' | 'PENDING_USER_ONBOARDING' | 'PENDING_MERCHANT_RELEASE'
    - `payoutMethod` 'BANK_ACCOUNT' | 'CRYPTO_WALLET' | 'CARD'
    - `customerConfirmedAt` number
    - `processedAt` number
    - `refundedAt` number
    - `resultCode` string
    - `resultMessage` string
    - `cardLast4` string
    - `bankAccountLast4` string

## Other responses

- `400` — Bad request
- `401` — Unauthorized

---

[API](https://skmtc.dev/breeze/apis/breeze-api.md) · [All operations](https://skmtc.dev/breeze/apis/breeze-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/breeze/breeze-api/revisions/8911892bdf29/schema)