> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usecleff.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.



## OpenAPI

````yaml POST /v1/payouts
openapi: 3.0.0
info:
  title: Cleff API
  description: >-
    Payout orchestration platform. All endpoints under /v1/ require an API key
    in the Authorization header (Bearer ck_<env>_<id>_<secret>).
  version: 0.0.1
  contact: {}
servers: []
security: []
tags: []
paths:
  /v1/payouts:
    post:
      tags:
        - Payouts
      summary: Create a Payout Intent
      description: >-
        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.
      operationId: PayoutsController_create
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePayoutDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePayoutResponseDto'
        '401':
          description: Missing or invalid API key
      security:
        - api_key: []
components:
  schemas:
    CreatePayoutDto:
      type: object
      properties:
        beneficiary_id:
          type: string
          format: uuid
        bank_account_id:
          type: string
          format: uuid
          description: >-
            Destination BankAccount for this disbursement. Must belong to the
            targeted Beneficiary and be in `verified` status.
        amount_minor:
          type: number
          description: >-
            Amount in minor units (e.g. cents). Max 9007199254740991 (2^53−1) to
            preserve JS integer precision.
          maximum: 9007199254740991
        currency:
          type: string
          description: ISO 4217 currency code
        idempotency_key:
          type: string
          description: >-
            Caller-supplied idempotency key, scoped to (Business, environment);
            24h short-circuit window.
        purpose_of_payment:
          type: string
          enum:
            - 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
          description: >-
            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.
        external_ref:
          type: string
          description: Business-supplied reference (e.g. tradeId/jobId).
        validator_strategy:
          type: string
          enum:
            - manual
          description: >-
            Override the per-Business default validator strategy for this
            Intent.
        replaces_payout_id:
          type: string
          format: uuid
          description: >-
            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:
          type: object
          description: >-
            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.
      required:
        - beneficiary_id
        - bank_account_id
        - amount_minor
        - currency
        - idempotency_key
        - purpose_of_payment
    CreatePayoutResponseDto:
      type: object
      properties:
        payout:
          $ref: '#/components/schemas/PayoutDto'
      required:
        - payout
    PayoutDto:
      type: object
      properties:
        id:
          type: string
        state:
          type: string
          enum:
            - pending_approval
            - approved
            - rejected
            - disbursed
            - failed
            - returned
            - canceled
            - settled
            - compliance_hold
        beneficiary_id:
          type: string
        bank_account_id:
          type: string
        beneficiary_name:
          type: object
          nullable: true
        beneficiary_type:
          type: string
          enum:
            - person
            - business
          nullable: true
        amount_minor:
          type: number
        purpose_of_payment:
          type: string
          enum:
            - 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
          description: Why the funds were sent. Provisional corridor-agnostic set.
        currency:
          type: string
        external_ref:
          type: object
          nullable: true
        idempotency_key:
          type: string
        validator_strategy:
          type: string
          enum:
            - manual
        environment:
          type: string
          enum:
            - sandbox
            - production
        provider:
          type: object
          nullable: true
        provider_payout_id:
          type: object
          nullable: true
        rail_ref:
          type: object
          nullable: true
        replaces_payout_id:
          type: object
          nullable: true
        created_at:
          type: string
          format: date-time
        via:
          type: object
          nullable: true
          description: Channel through which the Intent arrived.
      required:
        - id
        - state
        - beneficiary_id
        - bank_account_id
        - amount_minor
        - purpose_of_payment
        - currency
        - external_ref
        - idempotency_key
        - validator_strategy
        - environment
        - provider
        - provider_payout_id
        - rail_ref
        - replaces_payout_id
        - created_at
  securitySchemes:
    api_key:
      scheme: bearer
      bearerFormat: ck_<env>_<id>_<secret>
      type: http
      description: >-
        Cleff API key issued to a Business that self-registers via POST
        /v1/registration

````