Customer Offramp Events

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

Each offramp event includes a payload structured like this:

{
  "type": "OFFRAMP_STATUS_UPDATE",
  "data": {
    "id": "ofrprq_abc123xyz",
    "status": "SUCCEEDED",
    "clientReferenceId": "offramp-<your-unique-id>",
    ...
  },
  "signature": "webhook_payload_signature"
}

Below are all possible offramp statuses and their meanings:

🎯 Core Offramp Statuses

Status	Description
CREATED	Default status when the offramp 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 offramp request expired after 7 days of unsuccessful attempts to deduct crypto due to insufficient balance.
CANCELED	The offramp 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" offramp 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 Offramp Statuses

These statuses mainly reflect Breeze’s internal processes during offramp handling. They help provide transparency, as offramps 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 offramp can proceed.
PENDING_USER_WITHDRAWAL	Waiting for the user to review and approve the offramp. 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 offramp wallet. If sufficient balance is available, this typically completes within 1 minute.
PENDING_MANUAL_INVESTIGATION	The offramp 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 Offramp Statuses in your application logic to accurately reflect offramp status to your customers.
Optionally monitor Supplementary Statuses if detailed visibility into the offramp lifecycle is needed.
Utilize webhook signatures to verify authenticity of Breeze offramp webhooks.