Headless Payout

🚧

Note: This endpoint is only available to merchants configured by the Breeze team. Please reach out to the Breeze team to get access.

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.

❗️

Do not proceed until the status is approved. If the status is pending, wait for Breeze's review to complete (<24h SLA). Attempting to trigger a payout for a customer without an approved status will result in an error.

Step 2 — Create a Headless Payout

To trigger a payout, send a POST request via 📄 API Reference — Create a headless payout

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

⚠️

You are responsible for handling the refund flow on your end. When a payout is returned by the receiving bank (e.g. due to a name mismatch or invalid account), Breeze will re-credit the funds to your balance and set the payout status to REFUNDED. You must listen for this status via webhook and handle the downstream impact to your user — including notifying them of the failed payout and prompting them to resubmit with corrected bank details if applicable.

Balance Management