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.

PAYMENT_CREATED* — Payment page created; customer hasn't paid yet. Sent only for merchants onboarded after 25 Aug 2025.
PAYMENT_SUCCEEDED — or — PAYMENT_EXPIRED — Customer pays → PAYMENT_SUCCEEDED. Page times out unpaid → PAYMENT_EXPIRED.
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": "uQ3.."
}

{
  "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-terminal	Terminal
`new`, `processing`	`succeeded`, `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-terminal	Terminal
`CREATED`, `PENDING`, `PROCESSING`	`PROCESSED`, `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-terminal	Terminal
`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-terminal	Terminal
`INCOMPLETE`, `TRIALING`, `SCHEDULED`, `ACTIVE`, `DISCOUNTED_TRIALING`, `GRACE_PERIOD`, `SUSPENDED`	`CANCELED`, `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-terminal	Terminal
`PENDING`, `GRACE_PERIOD`	`PAID`, `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-terminal	Terminal
`pending`, `processing`, `under_review`	`approved`, `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-terminal	Terminal
`RECEIVED`, `EVIDENCE_REQUIRED`, `EVIDENCE_SUBMITTED`, `EVIDENCE_UNDER_REVIEW`, `EVIDENCE_ACKNOWLEDGED_BY_SCHEME`, `ARBITRATION_SENT_TO_SCHEME`	`EXPIRED`, `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-terminal	Terminal
`PENDING_DEPOSIT_VALIDATION`, `DEPOSIT_CONFIRMED`, `TRADE_PENDING`, `TRADE_EXECUTING`, `SETTLEMENT_PENDING`	`COMPLETED`, `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..."
}

Status	Description
`CARD_OPTIONS_RESTRICTED`	The user's card options are restricted because Breeze has detected fraudulent or suspicious activity within the Breeze ecosystem..
`OFFBOARDED`	The user has been denied access to Breeze services for compliance reasons..
`ACTIVE`	The 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..

Gift card events

Here's a field table for the GIFT_CARD_ISSUED payload, matching the style used elsewhere on the page:

Field	Description
`giftCardId`	Unique identifier for the gift card.
`transactionId`	ID of the payment transaction that issued the card (`py_` prefix).
`splitIndex`	If the transaction exceeded the max face value and was split across multiple cards, this marks the card's position in that split, starting at `0`. Single-card purchases are always `0`.
`faceValue`	Value of the gift card, in minor units (cents).
`currency`	ISO currency code of the gift card.
`status`	Current state of the gift card. See status table below.

And a status table, matching the USER_REVIEW_UPDATE pattern:

Status	Description
`issued`	The gift card has been created and is ready to use.
`redeemed`	The gift card has been fully used against a purchase.
`refunded`	The gift card's value has been refunded.

{
  "type": "GIFT_CARD_ISSUED",
  "data": {
    "giftCardId": "gc_abc123xyz",
    "pageId": "page_abc123xyz",
    "paymentId": "py_123xyz",
    "splitIndex": 0,
    "faceValue": 10000,
    "currency": "USD",
    "status": "issued"
  },
  "signature": "afZiTJ..."
}

{
  "type": "GIFT_CARD_REDEEMED",
  "data": {
    "giftCardId": "gc_abc123xyz",
    "pageId": "page_abc123xyz",
    "paymentId": "py_123xyz",
    "splitIndex": 0,
    "faceValue": 10000,
    "currency": "USD",
    "status": "redeemed"
  },
  "signature": "afZiTJ..."
}

{
  "type": "GIFT_CARD_REFUNDED",
  "data": {
    "giftCardId": "gc_abc123xyz",
    "pageId": "page_abc123xyz",
    "paymentId": "py_123xyz",
    "splitIndex": 0,
    "faceValue": 10000,
    "currency": "USD",
    "status": "refunded"
  },
  "signature": "afZiTJ..."
}