Breeze.cash Headless Payout API

openapi: 3.2.0
info:
  title: Breeze Headless Payout API
  version: 1.0.0
  description: Breeze payment processing API
  contact:
    email: support@breeze.cash
    url: https://docs.breeze.cash
servers:
- url: https://api.breeze.cash
  description: Breeze API
- url: https://secure.breeze.cash
  description: Breeze Direct Payment API (production)
- url: https://secure-sandbox.breeze.cash
  description: Breeze Direct Payment API (sandbox)
security:
- basicAuth: []
tags:
- name: Headless Payout
paths:
  /v1/headless_payout:
    post:
      operationId: createHeadlessPayout
      tags:
      - Headless Payout
      summary: Create a headless payout
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                description: The created payout page in PROCESSING status
                properties:
                  status:
                    type: string
                    enum:
                    - SUCCEEDED
                  data:
                    $ref: '#/components/schemas/CreateHeadlessPayoutResponse'
                required:
                - status
                - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      description: 'Creates a payout for a KYC-verified customer in a single API call. Validates the customer has active TIER_2 KYC, creates or reuses the destination bank account, and initiates the payout. Idempotent on clientReferenceId.


        Provide exactly one destination, and the matching `currency`:

        - `bankAccount` (US ACH): `currency` must be `USD`.

        - `sepaBankAccount` (SEPA): `currency` must be `EUR`. The account holder is checked with Verification of Payee before the account is saved; a failed check is returned as `BANK_ACCOUNT_VOP_VERIFICATION_FAILED` and nothing is created.


        The amount is paid out in `currency` with no conversion. Each currency needs a matching payout wallet on your merchant account, and the corresponding payout rail must be enabled.


        `customerIpAddress` is the IP address the customer consented to the payout from. Pass it when you collected it; when omitted, the consent IP recorded with the customer''s headless KYC request is used, and the call fails with `RESOURCE_NOT_FOUND` if the customer was not verified through the Headless KYC API.


        **Note:** This endpoint requires the customer to have active TIER_2 KYC, for example through 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.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateHeadlessPayoutRequest'
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - FAILED
        errorCode:
          type: string
        errorMessage:
          type: string
      required:
      - status
      - errorCode
      - errorMessage
    CreateHeadlessPayoutResponse:
      $schema: http://json-schema.org/draft-07/schema#
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          enum:
          - CREATED
          - PENDING
          - PROCESSING
          - PROCESSED
          - ON_HOLD
          - REFUNDED
          - EXPIRED
          - CANCELLED
          - REJECTED
        amount:
          type: number
        fundingCurrency:
          type: string
          enum:
          - USDC
          - USDCE
          - USDBC
          - USDT
          - EURC
          - DAI
          - BUSD
          - BTC
          - ETH
          - BNB
          - MATIC
          - POL
          - AVAX
          - SOL
          - TRX
          - KAP
          - ARB
          - CBBTC
          - PYUSD
          - SNS
          - HONEY
        payoutDestinationRail:
          type: string
          enum:
          - ach
          - sepa
          - card_usd
          - breeze_card_usd
          - zengin
          - twd_fisc
          - hkd_fps
          - krw_kftc
          - gbp_fps
        clientReferenceId:
          type: string
        releaseMethod:
          type: string
          enum:
          - MANUAL
          - AUTOMATIC
        merchant:
          type: object
          properties:
            id:
              type: string
            livemode:
              type: boolean
          required:
          - id
          - livemode
        customer:
          type: object
          properties:
            id:
              type: string
            referenceId:
              type: string
            email:
              type: string
          required:
          - email
        successReturnUrl:
          type: string
        failureReturnUrl:
          type: string
        url:
          type: string
        pendingStatus:
          type: string
          enum:
          - PENDING_USER_CONFIRMATION
          - PENDING_USER_ONBOARDING
          - PENDING_MERCHANT_RELEASE
        payoutMethod:
          type: string
          enum:
          - BANK_ACCOUNT
          - CRYPTO_WALLET
          - CARD
          - BREEZE_CARD
        customerConfirmedAt:
          type: number
        processedAt:
          type: number
        refundedAt:
          type: number
        resultCode:
          type: string
        resultMessage:
          type: string
        cardLast4:
          type: string
        bankAccountLast4:
          type: string
      required:
      - id
      - status
      - amount
      - fundingCurrency
      - clientReferenceId
      - releaseMethod
      - merchant
      - customer
      - url
      definitions: {}
    CreateHeadlessPayoutRequest:
      description: Headless payout details
      type: object
      properties:
        amount:
          type: integer
          exclusiveMinimum: 0
        currency:
          type: string
          enum:
          - USD
          - EUR
        clientReferenceId:
          type: string
          minLength: 1
          maxLength: 255
        releaseMethod:
          type: string
          enum:
          - MANUAL
          - AUTOMATIC
        customer:
          type: object
          properties:
            id:
              type: string
            referenceId:
              type: string
            email:
              type: string
              format: email
          required:
          - email
          additionalProperties: false
          oneOf:
          - required:
            - id
            title: By Id
          - required:
            - referenceId
            title: By Reference Id
          - not:
              oneOf:
              - required:
                - id
              - required:
                - referenceId
              - required:
                - id
                - referenceId
            title: Neither
        customerIpAddress:
          type: string
          oneOf:
          - format: ipv4
          - format: ipv6
        bankAccount:
          type: object
          properties:
            accountNumber:
              type: string
              minLength: 4
              maxLength: 17
              pattern: ^\d+$
            routingNumber:
              type: string
              pattern: ^\d+$
            accountType:
              type: string
              enum:
              - checking
              - savings
          required:
          - accountNumber
          - routingNumber
          - accountType
          additionalProperties: false
        sepaBankAccount:
          type: object
          properties:
            iban:
              type: string
              minLength: 15
              maxLength: 34
            accountHolderName:
              type: string
              minLength: 1
            bic:
              type: string
              pattern: ^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$
          required:
          - iban
          - accountHolderName
          - bic
          additionalProperties: false
      required:
      - amount
      - currency
      - clientReferenceId
      - releaseMethod
      - customer
      additionalProperties: false
      oneOf:
      - required:
        - bankAccount
      - required:
        - sepaBankAccount
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: API key as username, empty password
x-provenance:
  method: searched
  source: https://docs.breeze.com/reference
  harvested: '2026-10-28'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://docs.breeze.com/reference/cancelofframprequest.md
  - https://docs.breeze.com/reference/cancelpayoutpage.md
  - https://docs.breeze.com/reference/cancelsubscription.md
  - https://docs.breeze.com/reference/createcustomer.md
  - https://docs.breeze.com/reference/creategatewaypayment.md
  - https://docs.breeze.com/reference/createheadlesspayout.md
  - https://docs.breeze.com/reference/createliquidationaddress.md
  - https://docs.breeze.com/reference/createofframprequest.md
  - https://docs.breeze.com/reference/createpaymentpage.md
  - https://docs.breeze.com/reference/createpayoutpage.md
  - https://docs.breeze.com/reference/createproduct.md
  - https://docs.breeze.com/reference/createproductprice.md
  - https://docs.breeze.com/reference/createsubscription.md
  - https://docs.breeze.com/reference/deletegatewaycustomerpaymentmethod.md
  - https://docs.breeze.com/reference/downloadstatement.md
  - https://docs.breeze.com/reference/expirepaymentpage.md
  - https://docs.breeze.com/reference/getallpaymentattempts.md
  - https://docs.breeze.com/reference/getcustomerbyid.md
  - https://docs.breeze.com/reference/getcustomerbyquery.md
  - https://docs.breeze.com/reference/getfraudreport.md
  - https://docs.breeze.com/reference/getgatewaypayment.md
  - https://docs.breeze.com/reference/getheadlesskycbycustomerreferenceid.md
  - https://docs.breeze.com/reference/getheadlesskycbyid.md
  - https://docs.breeze.com/reference/getinvoice.md
  - https://docs.breeze.com/reference/getliquidationaddress.md
  - https://docs.breeze.com/reference/getliquidationaddresstransaction.md
  - https://docs.breeze.com/reference/getmerchanttaxrate.md
  - https://docs.breeze.com/reference/getofframprequest.md
  - https://docs.breeze.com/reference/getpaymentpage.md
  - https://docs.breeze.com/reference/getpayoutpage.md
  - https://docs.breeze.com/reference/getpayoutpagehistory.md
  - https://docs.breeze.com/reference/getproduct.md
  - https://docs.breeze.com/reference/getrefund.md
  - https://docs.breeze.com/reference/getriskstatus.md
  - https://docs.breeze.com/reference/getsubscription.md
  - https://docs.breeze.com/reference/getsubscriptionbyclientreferenceid.md
  - https://docs.breeze.com/reference/initiateheadlesskyctier3.md
  - https://docs.breeze.com/reference/initiaterefund.md
  - https://docs.breeze.com/reference/listdisputes.md
  - https://docs.breeze.com/reference/listfraudreports.md
  - https://docs.breeze.com/reference/listgatewaycustomerpaymentmethods.md
  - https://docs.breeze.com/reference/listliquidationaddresses.md
  - https://docs.breeze.com/reference/listliquidationaddresstransactions.md
  - https://docs.breeze.com/reference/listpaymentpages.md
  - https://docs.breeze.com/reference/listproducts.md
  - https://docs.breeze.com/reference/liststatements.md
  - https://docs.breeze.com/reference/listsubscriptions.md
  - https://docs.breeze.com/reference/offboardcustomer.md
  - https://docs.breeze.com/reference/releaseofframprequest.md
  - https://docs.breeze.com/reference/releasepayoutpage.md
  - https://docs.breeze.com/reference/resumegatewaypaymentauthentication.md
  - https://docs.breeze.com/reference/sandboxconfirmpayoutpage.md
  - https://docs.breeze.com/reference/simulatesandboxdispute.md
  - https://docs.breeze.com/reference/submitheadlesskycproofofaddresswithupload.md
  - https://docs.breeze.com/reference/submitheadlesskycproofofaddresswithurl.md
  - https://docs.breeze.com/reference/submitheadlesskycwithimageupload.md
  - https://docs.breeze.com/reference/submitheadlesskycwithimageurl.md
  - https://docs.breeze.com/reference/updatecustomer.md
  merge:
    pages: 58
    deduped: 458
    conflicts_kept_first: 0