Headless Payout

This guide explains how to trigger payouts to KYC-approved customers directly via the Breeze API, without any Breeze-hosted pages or redirects. You own the entire customer-facing experience — Breeze handles bank rail selection, fund management, and transfer processing under the hood.

Prerequisites

1. This endpoint requires the customer to have been KYC-verified via the Headless KYC API with an approved status. See Headless KYC to set this up first before proceeding.
2. Either the customerId or customerReferenceId from the Headless KYC API call should be passed in as customer.id or customer.referenceId when creating the Payout Page.

How It Works (Conceptual Overview)

sequenceDiagram
    participant Merchant
    participant Customer
    participant Breeze

    Note over Merchant: Step 1 – Verify KYC is approved
    Merchant->>Breeze: GET /v1/headless_kyc?customerReferenceId={id}
    Breeze-->>Merchant: Return KYC status = approved

    Note over Merchant, Breeze: Step 2 – Trigger payout
    Merchant->>Breeze: POST /v1/headless_payout (customer ID + amount + bank details)
    Breeze->>Breeze: Verify KYC status, check balance, select rail
    Breeze-->>Merchant: Payout initiated

    Note over Merchant, Customer: Step 3 – Notify customer
    Merchant->>Customer: Notify of payout status in your UI

Integration Steps

Step 1 — Verify KYC is Approved

Before triggering a payout, confirm the customer's KYC status is approved either by listening to the webhooks, or by polling. See Step 4 — Handling Updates from Breeze for more details.

Step 2 — Create a Headless Payout

To trigger a payout, send a POST request to the Breeze API. See 📄 API Reference — Create a headless payout for the full request/response schema.

curl -X POST 'https://api.breeze.cash/v1/headless_payout' \
  -u "YOUR_API_KEY:" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "clientReferenceId": "payout-ref-001",
    "amount": 1000,
    "currency": "USD",
    "releaseMethod": "AUTOMATIC",
    "customer": {
      "referenceId": "<your-unique-user-id>",
      "email": "[email protected]"
    },
    "bankAccount": {
      "routingNumber": "021000021",
      "accountNumber": "123456789",
      "accountType": "checking"
    }
  }'

This endpoint is idempotent on clientReferenceId.

Request Payload

What Breeze Does

Upon receiving the request, Breeze will:

• Verify the customer's approved KYC status
• Check your pre-funded balance (queues payout if insufficient)
• Attach the KYC-verified legal name to the transfer
• Auto-select RTP (near-instant) or ACH (1–3 business days) based on the receiving bank's capability
  
  

  ⚠️

  Name-match risk: The receiving bank checks the transfer name against the account holder. A mismatch will result in the transfer being returned (typically 2–5 business days). Returned funds are automatically re-credited to your balance.

Step 3 — Handle Payout Status Updates via Webhooks

Breeze sends webhook notifications to your configured endpoint whenever a payout status changes. You should not rely on the initial API response alone — implement webhook handling to track the full lifecycle of each payout.

See Webhook Events for Payout Pages for the full list of events and payload details.

See Payout Page Statuses and Sub-Statuses for the full breakdown of statuses and sub-statuses.

Once the payout is initiated, notify your user of the status within your own UI. You are responsible for all customer-facing communication.

Handling Refunds

Balance Management