Guides

Webhook Event Reference

Full payload examples for every Breeze webhook event, grouped by category.

For the event envelope format, retry behavior, and signature verification, see Webhooks Overview.

ℹ️

Events marked with * are not enabled by default. See the Supported Events table for gating details.

Typical Event Sequences

Understanding which events fire — and in what order — helps you build a reliable webhook handler.

  1. PAYMENT_CREATED* — Payment page created; customer hasn't paid yet. Sent only for merchants onboarded after 25 Aug 2025.
  2. PAYMENT_SUCCEEDED — or — PAYMENT_EXPIRED — Customer pays → PAYMENT_SUCCEEDED. Page times out unpaid → PAYMENT_EXPIRED.
  3. PAYMENT_ATTEMPT_FAILED* — Card declined. The page stays open so the customer can retry. Not sent by default — contact support to enable.

Payin Events

{
  "type": "PAYMENT_CREATED",
  "data": {
    "pageId": "pay_abc123xyz",
    "status": "UNPAID",
    "clientReferenceId": "<your-unique-id>",
    "customer": {
      "id": "cus_abc123xyz",
      "referenceId": "<your-customer-id>",
      "email": "[email protected]"
    },
    "currency": "USD",
    "amount": 100,
    "source": "direct"
  },
  "signature": "afZiTJ..."
}
{
  "type": "PAYMENT_SUCCEEDED",
  "data": {
    "pageId": "page_abc123xyz",
    "billingEmail": "[email protected]",
    "status": "PAID",
    "clientReferenceId": "<your-unique-id>",
    "customer": {
      "id": "cus_abc123xyz",
      "referenceId": "<your-customer-id>",
      "email": "[email protected]"
    },
    "currency": "USD",
    "amount": 100,
    "payinDetails": {
      "amount": 100,
      "taxAmount": 6,
      "currency": "USD",
      "type": "CARD",
      "scheme": "AMEX",
      "last4": "0602",
      "cardType": "CREDIT",
      "bin": "377910",
      "issuer": "DBS BANK LTD",
      "threeDS": {
        "requested": true,
        "authenticationStatusCode": "Y",
        "flow": "CHALLENGE",
        "eci": "05"
      }
    },
    "source": "direct"
  },
  "signature": "afZiTJ..."
}
{
  "type": "PAYMENT_EXPIRED",
  "data": {
    "pageId": "page_abc123xyz",
    "status": "EXPIRED",
    "clientReferenceId": "<your-unique-id>",
    "customer": {
      "id": "cus_abc123xyz",
      "referenceId": "<your-customer-id>",
      "email": "[email protected]"
    },
    "currency": "USD",
    "amount": 100,
    "source": "direct"
  },
  "signature": "afZiTJ..."
}
{
  "type": "PAYMENT_ATTEMPT_FAILED",
  "data": {
    "pageId": "page_123xyz",
    "paymentId": "py_123xyz",
    "currency": "USD",
    "amount": 500,
    "status": "UNPAID",
    "errorCode": "PAYMENT_DECLINED_PROVIDER",
    "failureReason": "Payment failed. Please check your card details and balance, or try another card. If the issue persists, contact your bank or support.",
    "source": "direct"
  },
  "signature": "MfBK123xyz..."
}

status is always UNPAID — this event is non-terminal. The payment page remains live and the customer can retry. payinDetails is not included in this payload.

{
  "type": "PAYMENT_ATTEMPT_AUTHORIZED",
  "data": {
    "pageId": "page_01HXYZABCDEF",
    "paymentId": "py_01HXYZ123456",
    "currency": "USD",
    "amount": 4999,
    "status": "PENDING_CAPTURE",
    "clientReferenceId": "order-7421",
    "schemeTransactionId": "019876543210123",
    "savedPaymentMethodId": "spm_01HXYZSAVED01",
    "customer": {
      "id": "cus_01HXYZCUST001",
      "referenceId": "merchant-customer-882",
      "email": "[email protected]"
    },
    "payinDetails": {
      "type": "card",
      "scheme": "visa",
      "bin": "411111",
      "last4": "1111",
      "cardType": "credit",
      "expiryMonth": 12,
      "expiryYear": 2029,
      "threeDS": {
        "requested": true,
        "flow": "FRICTIONLESS",
        "eci": "05",
        "authentication_status_code": "Y"
      }
    }
  },
  "signature": "k8VqJ2g6m4u3X1pYbN0wTzR5sF7hC9aE2dQ8oU1iL4o="
}
{
  "type": "PAYMENT_ATTEMPT_CAPTURED",
  "data": {
    "pageId": "page_01HXYZABCDEF",
    "paymentId": "py_01HXYZ123456",
    "currency": "USD",
    "amount": 4999,
    "status": "CONFIRMED",
    "clientReferenceId": "order-7421",
    "schemeTransactionId": "019876543210123",
    "customer": {
      "id": "cus_01HXYZCUST001",
      "referenceId": "merchant-customer-882",
      "email": "[email protected]"
    },
    "payinDetails": {
      "type": "card",
      "scheme": "visa",
      "bin": "411111",
      "last4": "1111",
      "cardType": "credit",
      "expiryMonth": 12,
      "expiryYear": 2029
    }
  },
  "signature": "L9oVqRpA7n2u8YbT4mC1xE6fG3dH0kJ5sQ2wU8iN1zE="
}
{
  "type": "REFUND_STATUS_UPDATE",
  "data": {
    "pageId": "page_abc123xyz",
    "refundId": "ref_pay_abc123xyz",
    "status": "new",
    "refundAmount": 641,
    "pageAmount": 641,
    "currency": "USD",
    "checkoutPaymentId": "pay_abc123xyz",
    "reason": "The refund reason",
    "operator": "[email protected]"
  },
  "signature": "uQ3..."
}
Non-terminalTerminal
new, processingsucceeded, failed

Payout Events

{
  "type": "PAYOUT_PAGE_STATUS_UPDATE",
  "data": {
    "id": "payout_page_abc123xyz",
    "status": "CREATED",
    "amount": 100,
    "fundingCurrency": "USDC",
    "clientReferenceId": "<your-unique-id>",
    "releaseMethod": "AUTOMATIC",
    "customer": {
      "id": "cus_abc123xyz",
      "referenceId": "<your-customer-id>",
      "email": "[email protected]"
    },
    "successReturnUrl": "https://example.com/success",
    "failureReturnUrl": "https://example.com/failure"
  },
  "signature": "DpUx..."
}
Non-terminalTerminal
CREATED, PENDING, PROCESSINGPROCESSED, REFUNDED, EXPIRED, CANCELLED, REJECTED
{
  "type": "PAYOUT_PAGE_PENDING_STATUS_UPDATE",
  "data": {
    "id": "payout_page_abc123xyz",
    "status": "PENDING",
    "amount": 100,
    "fundingCurrency": "USDC",
    "clientReferenceId": "<your-unique-id>",
    "releaseMethod": "MANUAL",
    "customer": {
      "id": "cus_abc123xyz",
      "referenceId": "<your-customer-id>",
      "email": "[email protected]"
    },
    "successReturnUrl": "https://example.com/success",
    "failureReturnUrl": "https://example.com/failure",
    "pendingStatus": "PENDING_MERCHANT_RELEASE",
    "payoutMethod": "BANK_ACCOUNT"
  },
  "signature": "DpUx..."
}
Non-terminalTerminal
PENDING_USER_CONFIRMATION, PENDING_USER_ONBOARDING, PENDING_INTERNAL_REVIEW, PENDING_MERCHANT_RELEASE—

Subscription & Invoice Events

{
  "type": "SUBSCRIPTION_STATUS_UPDATED",
  "data": {
    "id": "subs_abc123xyz",
    "createdAt": 1763717623452,
    "updatedAt": 1768901949735,
    "clientReferenceId": "<your-unique-id>",
    "status": "SUSPENDED",
    "priceId": "prc_abc123xyz",
    "productId": "prd_abc123xyz",
    "amount": 599,
    "currency": "USD",
    "billingCycleConfig": {
      "interval": "week",
      "frequency": 1
    },
    "customerId": "cus_abc123xyz"
  },
  "signature": "4SsvB..."
}
Non-terminalTerminal
INCOMPLETE, TRIALING, SCHEDULED, ACTIVE, DISCOUNTED_TRIALING, GRACE_PERIOD, SUSPENDEDCANCELED, INCOMPLETE_EXPIRED
{
  "type": "INVOICE_STATUS_UPDATED",
  "data": {
    "id": "invc_abc123xyz",
    "customerId": "cus_abc123xyz",
    "dueAt": 1758706742140,
    "expiredAt": 1763890742140,
    "livemode": false,
    "merchantId": "mch_abc123xyz",
    "statusUpdatedAt": 1758704448814,
    "status": "PENDING",
    "amount": 301,
    "currency": "USD",
    "previousInvoiceId": "invc_abc123xyz",
    "subscriptionId": "subs_abc123xyz",
    "paymentPageId": "page_abc123xyz",
    "billingPeriod": {
      "start": 1758706742140,
      "end": 1758710342140
    }
  },
  "signature": "afZiTJ..."
}
Non-terminalTerminal
PENDING, GRACE_PERIODPAID, EXPIRED, CANCELED

KYC & Fraud Events

{
  "type": "KYC_DATA_REQUIRED",
  "data": {
    "email": "[email protected]"
  },
  "signature": "afZiTJ..."
}
{
  "type": "HEADLESS_KYC_STATUS_UPDATED",
  "data": {
    "id": "hkr_abc123xyz",
    "customerId": "cus_abc123xyz",
    "kycId": "kyc_abc123xyz",
    "kycStatus": "approved",
    "customerReferenceId": "<your-customer-reference-id>",
    "tier": "TIER_2",
    "rejectionReason": null,
    "createdAt": 1763717623452,
    "updatedAt": 1768901949735
  },
  "signature": "afZiTJ..."
}
Non-terminalTerminal
pending, processing, under_reviewapproved, rejected
{
  "type": "FRAUD_REPORTED",
  "data": {
    "pageId": "page_abc123xyz",
    "clientReferenceId": "<your-payment-page-unique-id>",
    "fraudReportId": "pay_abc123xyz",
    "fraudReason": "Card Not Present Fraud"
  },
  "signature": "afZiTJ..."
}

Dispute Events

{
  "type": "DISPUTE_STATUS_UPDATE",
  "data": {
    "id": "dp_xxxxxx",
    "createdAt": 1757374102012,
    "updatedAt": 1757374102112,
    "sourceUpdatedAt": 1757374132012,
    "livemode": true,
    "email": "[email protected]",
    "paymentPageId": "page_xxxxxx",
    "status": "RECEIVED"
  },
  "signature": "example_webhook_signature"
}
Non-terminalTerminal
RECEIVED, EVIDENCE_REQUIRED, EVIDENCE_SUBMITTED, EVIDENCE_UNDER_REVIEW, EVIDENCE_ACKNOWLEDGED_BY_SCHEME, ARBITRATION_SENT_TO_SCHEMEEXPIRED, ACCEPTED, LOST, ARBITRATION_LOST, RESOLVED, CANCELED, WON, ARBITRATION_WON

Crypto Events

LIQUIDATION_ADDRESS_TRANSACTION_STATUS_UPDATE fires when a customer sends crypto to their dedicated deposit address and Breeze processes the conversion and settlement.

{
  "type": "LIQUIDATION_ADDRESS_TRANSACTION_STATUS_UPDATE",
  "data": {
    "id": "lat_abc123xyz",
    "liquidationAddressId": "la_abc123xyz",
    "livemode": true,
    "status": "COMPLETED",
    "depositTransactionHash": "0xabc123...",
    "depositAmount": "100.00",
    "depositCurrency": "USDC",
    "depositNetwork": "ETH",
    "depositConfirmedAt": 1763717623452,
    "fromAddress": "0xdef456...",
    "settlementAmount": "99.50",
    "settlementCurrency": "USD",
    "settlementTransactionHash": "0xghi789...",
    "settlementConfirmedAt": 1763717700000
  },
  "signature": "afZiTJ..."
}
Non-terminalTerminal
PENDING_DEPOSIT_VALIDATION, DEPOSIT_CONFIRMED, TRADE_PENDING, TRADE_EXECUTING, SETTLEMENT_PENDINGCOMPLETED, FAILED, CANCELLED

Team & Membership Events

{
  "type": "CONNECT_SUCCEEDED",
  "data": {
    "connectId": "conn_52c1c788d831dcd4",
    "email": "[email protected]",
    "relationship": "VIEWER"
  },
  "signature": "gbWV..."
}
{
  "type": "CONNECT_DELETED",
  "data": {
    "connectId": "conn_52c1c788d831dcd4",
    "email": "[email protected]",
    "relationship": "VIEWER"
  },
  "signature": "afZiTJ..."
}

User review update events

This event fires when Breeze completes a risk or compliance review on an end-user account, resulting in a status change. Detailed review findings are not included in the webhook payload. For detailed review updates, contact Breeze Support to subscribe via your dedicated support Slack channel.

{
  "type": "USER_REVIEW_UPDATE",
  "data": {
    "userEmail": "[email protected]",
    "status": "CARD_OPTIONS_RESTRICTED"
  },
  "signature": "afZiTJ..."
}
StatusDescription
CARD_OPTIONS_RESTRICTEDThe user's card options are restricted because Breeze has detected fraudulent or suspicious activity within the Breeze ecosystem..
OFFBOARDEDThe user has been denied access to Breeze services for compliance reasons..
ACTIVEThe user is active and no longer subject to card restrictions. This status is sent via webhook only when the user was previously in a restricted state and restrictions have since been lifted following review..