Overview

This document describes how to listen for payment-related tracking events emitted by the Breeze payment iframe via the browser's postMessage API. These events allow the host (parent) page to monitor user interactions within the embedded Breeze payment form — including button clicks, form field entries, impressions, validation errors, and payment outcomes — without directly accessing the iframe's DOM. This is useful for analytics, conversion funnel tracking, and triggering custom UI behavior in response to payment flow activity.

Usage

Register a message event listener on the window object. Incoming messages with type === "on-payment-event" originate from the Breeze iframe. The specific event name is available at event.data.data.eventName.

// Register event listener for iframe messages
const handleIFrameRequest = (event: MessageEvent) => {
  if (event.data?.type === "on-payment-event") {
    // Handle the callback here
    handleEvent(event.data.data?.eventName);
  }
};

window.addEventListener("message", handleIFrameRequest);

Event Reference

EBreezePaymentEvent	Description
`payin_click_all_pay_button`	User clicks the main "Pay" button (universal pay button for all payment methods).
`payin_click_all_retry_button`	User clicks the "Retry" button (universal retry button for all payment methods).
`payin_imprs_apple_pay_button`	Apple Pay button impression (user sees the Apple Pay entry point on the page).
`payin_imprs_google_pay_button`	Google Pay button impression (user sees the Google Pay entry point on the page).
`payin_click_apple_pay_button`	User clicks the Apple Pay button, attempting to pay with Apple Pay.
`payin_click_google_pay_button`	User clicks the Google Pay button, attempting to pay with Google Pay.
`payin_click_card_number_entered`	User has entered a card number (field input complete, e.g. on blur or passing basic format validation).
`payin_click_card_expiration_date_entered`	User has entered the card expiration date (e.g. full MM/YY).
`payin_click_card_cvv_entered`	User has entered the CVV/security code (length requirement met).
`payin_click_card_email_entered`	User has entered an email address (input complete / passes format validation).
`payin_click_card_first_name_entered`	User has entered a first name.
`payin_click_card_last_name_entered`	User has entered a last name.
`payin_click_card_zip_code_entered`	User has entered a ZIP code.
`payin_action_card_input_validation_error`	Card form input validation error triggered (e.g. card number, expiration date, CVV, or email field validation failed).
`payin_click_card_pay_button`	User clicks the card payment "Pay" button to submit payment.
`payin_click_card_retry_button`	User clicks the "Retry" button after a card payment failure.
`payin_click_pay_with_card_button`	User clicks the "Pay with Card" entry button (switching from another payment method to card payment).
`payin_action_google_pay_payment_success`	Google Pay payment succeeded.
`payin_action_apple_pay_payment_success`	Apple Pay payment succeeded.
`payin_imprs_card_details`	Card form impression (user sees the card input form on the page).
`payin_action_card_payment_success`	Card payment succeeded.
`payin_action_3ds_requested`	3DS requested
`payin_action_3ds_cancelled`	3DS request cancelled by user