Example Integration

For a complete example of how to integrate the Breeze Payment Page SDK, visit our demo repository.

You can also see the SDK in action on our live demo site.

Download the SDK

You can download the SDK by running:

npm install @breeze.cash/ui

yarn add @breeze.cash/ui

Embedding the payment page

You can get the pageId and clientSecret from creating a payment page endpoint.

import { BreezePaymentPage } from "@breeze.cash/ui";

...
return (
  <BreezePaymentPage
    pageId="page_xxxxxxxxxxxx"
    clientSecret="pcs_xxxxxxxxxxx"
  />
);
...

Props

Name	Type	Required	Description
pageId	`string`	✅	The page ID that is returned from create payment page endpoint. This uniquely identifies the payment made.
clientSecret	`string`	✅	This is returned from create payment page endpoint.
style	`CSSProperties`		CSS styles for the UI
onPaymentStatusChange	`(status: PaymentPageStatus) => void`		Callback when payment page status is changed `PaymentPageStatus = "UNPAID" \| "EXPIRED" \| "PAID"`
onPaymentEvent	`(event: string) => void`		Fires on UI interaction events. Use for analytics and tracking. See onPaymentEvent events below for the full list of event names. Use `onPaymentStatusChange` for payment status changes — `onPaymentEvent` is for UI interactions only.

`onPaymentEvent` events

The onPaymentEvent callback receives one of the following string event names:

Event name	Trigger
`payin_click_all_pay_button`	User clicks the main pay button
`payin_click_all_retry_button`	User clicks retry after a failure
`payin_imprs_apple_pay_button`	Apple Pay button becomes visible
`payin_imprs_google_pay_button`	Google Pay button becomes visible
`payin_click_apple_pay_button`	User clicks Apple Pay
`payin_click_google_pay_button`	User clicks Google Pay
`payin_click_pay_with_card_button`	User selects card payment method
`payin_click_card_number_entered`	User completes card number field
`payin_click_card_expiration_date_entered`	User completes expiration date field
`payin_click_card_cvv_entered`	User completes CVV field
`payin_click_card_email_entered`	User completes email field
`payin_click_card_first_name_entered`	User completes first name field
`payin_click_card_last_name_entered`	User completes last name field
`payin_click_card_zip_code_entered`	User completes zip code field
`payin_action_card_input_validation_error`	A card input field fails validation
`payin_click_card_pay_button`	User clicks pay on the card form
`payin_click_card_retry_button`	User clicks retry on the card form

Best Practices for `onPaymentStatusChange` callback

Use this for immediate UI updates to provide feedback to your customers (show loading states, success messages, etc.)

However, you should use our backend webhooks as the source of truth for fulfillment and business operations.

This separation is crucial because:

Customers might close the browser before frontend callbacks complete
Frontend code can be tampered with by malicious users
Some payment methods (like bank transfers) don't provide immediate confirmation

Never rely solely on frontend events for order fulfilment or critical business operations. The webhook system provides the reliable source of truth for payment statuses.

Enabling Apple Pay for SDK

To enable Apple Pay for SDK usage, please email [email protected] for the merchant domain certification to allow Apple Pay be enabled when the SDK is hosted on your domain

Adding the domain certification

When you receive the domain certification from our support, you have to host it on your domain at the path {YOUR_DOMAIN}/.well-known/apple-developer-merchantid-domain-association.txt

If you are using Vite, you can simply add the textfile under /public folder.