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"`

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 utilise our backend webhooks as the source of truth for fulfilment 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.