Payout Events

Breeze sends webhook events of type "PAYOUT_STATUS_UPDATE" whenever a payout’s status changes. Webhooks follow Breeze’s general webhook event format and security rules.

Each payout event includes a payload structured like this:

{
  "type": "PAYOUT_STATUS_UPDATE",
  "data": {
    "id": "payout_abc123xyz",
    "status": "SUCCEEDED",
    "clientReferenceId": "payout-<your-unique-id>",
    ...
  },
  "signature": "webhook_payload_signature"
}

Below are all possible payout statuses and their meanings:

🎯 Core Payout Statuses

Status	Description
CREATED	Default status when the payout request is initially created.
SUCCEEDED	Breeze has sent the deposit request to the user's bank account.- Note: This status does not guarantee that the funds have arrived. Actual availability depends on the processing speed of the user's bank.
EXPIRED	The payout request expired after 7 days of unsuccessful attempts to deduct crypto due to insufficient balance.
CANCELED	The payout request was explicitly canceled at your request.
REQUIRES_RELEASE	Waiting for your server to explicitly call Breeze's "release" API to proceed (applicable if you're integrating via the "manual" payout flow).
REFUNDED	Breeze attempted to send the deposit to the user’s bank account, but the transfer failed (e.g., due to an invalid bank account number or similar issue). The funds were returned to the Merchant, who is responsible for crediting the user back within their system.

📝 Supplementary Payout Statuses

These statuses mainly reflect Breeze’s internal processes during payout handling. They help provide transparency, as payouts typically involve more asynchronous and longer workflows compared to instant pay-ins.

Status	Description
PENDING_USER_ONBOARDING	The user needs to create a Breeze account, complete KYC, and link their bank account before the payout can proceed.
PENDING_USER_WITHDRAWAL	Waiting for the user to review and approve the payout. This is required for regulatory compliance before sending USD to a user's bank account.
PENDING_DEPOSIT_CRYPTO_MERCHANT	Waiting to deduct crypto from your payout wallet. If sufficient balance is available, this typically completes within 1 minute.
PENDING_MANUAL_INVESTIGATION	The payout has encountered an exception that requires manual review. For example, crypto has been deducted and ACH initiated, but an issue has occurred with the user's account.
IN_PROGRESS	Breeze has received crypto funds and is currently converting them to fiat, then initiating the ACH deposit. Typically completed in less than 5 minutes.

⚠️ Recommended Best Practices

Always handle Core Payout Statuses in your application logic to accurately reflect payout status to your customers.
Optionally monitor Supplementary Statuses if detailed visibility into the payout lifecycle is needed.
Utilize webhook signatures to verify authenticity of Breeze payout webhooks.