SDK reference
Overview
Embedded Checkout adds a global Checkout
object, with a single initiate
method.
export type CheckoutOptions = {
/**
* Checkout id retrieved from an API call to /v2/checkout
*/
checkoutId: string;
/**
* Entity id, needs to match the entity id used to create the checkout.
*/
key: string;
/**
* Options for the Checkout UI.
*/
options?: {
/**
* Custom ordering of payment methods.
*
* e.g.
* {
* card: 1,
* mobicred: 2,
* payflex: 3,
* }
*
*/
ordering?: Record<string, number>;
};
/**
* Event handlers.
*
* Hook into Checkout events, and perform actions when they occur.
*/
eventHandlers?: {
/**
* Event handlers fired when Checkout has completed successfully.
* @param event Details about the transaction.
* @returns Void
*/
onCompleted?: (event: CompletedCheckoutEvent) => void;
/**
* Event fired when Checkout has cancelled by the user.
* @param event Details about the Checkout.
* @returns Void
*/
onCancelled?: (event: CheckoutEvent) => void;
/**
* Event fired when Checkout has timed out.
* @param event Details about the Checkout.
* @returns Void
*/
onExpired?: (event: CheckoutEvent) => void;
/**
* Event fired just before submission of a payment.
*
* Can be used to block the payment from being submitted.
* Return true to allow payment, anything else (including no return) blocks it and shows an error message to the user.
* For blocked payments, the parent page should handle redirecting or unmounting checkout.
* If not handled, an error message is shown to the user.
*
* @example
* onBeforePayment: async () => {
* try {
* const isValid = await validatePayment();
* if (isValid) return true;
* throw new Error("Product out of stock!");
* } catch (error) {
* // Payment blocked, parent page should handle redirect/unmount
* // Handle redirecting or unmounting
* }
* }
*
* @returns {true|Promise<true>|void} True to proceed with payment, anything else (or no return) to block it
*/
onBeforePayment?: () => true | Promise<true> | void;
};
/**
* Customisations for the UI.
*/
customisations?: {
/**
* Controls visibility of the cancel button
* @default true
*/
showCancelButton?: boolean;
/**
* Controls visibility of the amount field
* @default true
*/
showAmountField?: boolean;
/**
* Controls visibility of the card brand display
* @default true
*/
showCardBrandDisplay?: boolean;
/**
* Custom theme options
*/
theme?: {
brand?: {
primary?: string;
secondary?: string;
};
cards?: {
background?: string;
backgroundHover?: string;
};
};
/**
* Card-specific UI customisation options
*/
card?: {
/**
* Text to display on the submit button
* @default "Pay Now"
*/
submitButtonText?: string;
/**
* Controls visibility of the card icon
* @default true
*/
showCardIcon?: boolean;
/**
* Text to show above the card payment in an h3
* @default "Please enter your card details below to complete the payment."
*/
headingText?: string;
};
};
};
export type RenderCheckout = {
/**
* Render Embedded Checkout into an HTML element.
* @param container ID of the HTML element to render Embedded Checkout into, or a direct reference to the HTML element itself.
*/
render: (container: string | HTMLElement) => void;
/**
* Remove Embedded Checkout from being rendered.
*
* NOTE: The same Checkout ID cannot be reused for another render attempt, a new ID will need to be generated.
*/
unmount: () => void;
};
export type Checkout = {
/**
* Initiate a Checkout UI experience.
* @param options Options for the Checkout experience.
* @returns An object that can be used to render the Checkout UI or to unmount the Checkout UI.
*/
initiate: (options: CheckoutOptions) => RenderCheckout;
};
Render
To render Embedded Checkout, initiate the Checkout object and then call checkout.render(...)
.
The render
call takes in the HTML ID of the element in the format #elementID
or takes in an HTML element directly:
checkout.render("#peachpayments-checkout");
const checkoutElement = document.getElementById("peachpayments-checkout");
checkout.render(checkoutElement);
Supporting the HTML element directly is useful in situations where you are using a shadow DOM.
Event handlers
Embedded Checkout supports handling events. When you specify a handler for an event, Embedded Checkout calls that handler event and does not redirect. If you don't specify a handler, Embedded Checkout redirects.
The following events are available:
Event | Description |
---|---|
onCompleted | The customer completes a payment and the checkout experience. |
onCancelled | The customer cancels the checkout experience. |
onExpired | The checkout experience expires (customers have 30 minutes to complete a payment). |
onBeforePayment | Fired before payment submission, allowing you to block the payment if needed. |
export type CheckoutEventHandlers = {
onCompleted?: (event: CompletedCheckoutEvent) => void;
onCancelled?: (event: CheckoutEvent) => void;
onExpired?: (event: CheckoutEvent) => void;
onBeforePayment?: () => true | Promise<true> | void;
};
Events
export type CheckoutEvent = {
amount: number;
checkoutId: string;
currency: string;
merchantTransactionId: string;
paymentType: "DB" | "PA";
result: {
code: string;
description: string;
};
signature: string;
timestamp: Date;
};
export type CompletedCheckoutEvent = CheckoutEvent & {
id: string;
merchant: {
name: string;
};
paymentBrand: string;
resultDetails: {
AcquirerResponse: string;
ConnectorTxID1: string;
ExtendedDescription: string;
};
};
{
amount: number;
checkoutId: string;
currency: string;
merchantTransactionId: string;
paymentType: "DB";
result: {
code: string;
description: string;
}
signature: string;
timestamp: Date;
id: string;
}
onBeforePayment
The onBeforePayment
event handler is useful for validating payments before you submit them:
eventHandlers: {
onBeforePayment: async () => {
try {
const isValid = await validatePayment();
if (isValid) return true;
throw new Error("Product out of stock!");
} catch (error) {
// Payment blocked, handle redirect/unmount
}
};
}
Return true
from onBeforePayment
to allow the payment to proceed. Handle any other return value (or no return value), otherwise Checkout shows an error to the user.
Theming
Embedded Checkout enables you to set the following colours:
-
Brand primary: Controls the cancel button font and border hover colour, the currency font colour, and the payment method card border hover colour.
Embedded Checkout with primary colour set to orange.
-
Brand secondary: Not used.
-
Cards background: Controls the payment method card background colour.
Embedded Checkout with payment method card background colour set to blue.
-
Cards background hover: Controls the payment method card background hover colour.
Embedded Checkout with payment method card background hover colour set to green.
Set the primary, secondary, and background colours as follows, ensuring that you use hexadecimal colour codes, for example, #000000
for black.
type Theme = {
brand?: {
primary?: string;
secondary?: string;
};
cards?: {
background?: string;
backgroundHover?: string;
};
};
Customise payment method order
Embedded Checkout enables you to specify the order of payment methods. This works by specifying an object with the payment method name and a number; lower numbers mean higher priority.
See the Payment methods section for more information on payment method parameter names.

Example Embedded Checkout with custom colours and payment method order; note that not all payment methods are available in all regions or for all currencies.
{
MASTERPASS: 1,
"1FORYOU": 2,
MOBICRED: 3,
CARD: 4,
}
Customise Checkout user interface
You can customise the Checkout user interface using the new customisations
property. This provides a flexible and feature-rich way to control the user interface:
- Basic user interface controls:
- Show or hide the cancel button
- Show or hide the amount field
- Show or hide the card brand display
- Theme customisation (colours, and so on)
- Card-specific customisations:
- Custom submit button text (default:
Pay Now
) - Show or hide card icon (default:
true
) - Custom heading text (default:
Please enter your card details below to complete the payment.
)
- Custom submit button text (default:

Embedded Checkout with the cancel button and amount removed.

Card payment form with the amount and card brand field removed.
type Customisations = {
showCancelButton?: boolean;
showAmountField?: boolean;
showCardBrandDisplay?: boolean;
theme?: Theme;
card?: {
submitButtonText?: string;
showCardIcon?: boolean;
headingText?: string;
};
};
Contact support to remove the billing fields from the Embedded Checkout card form.
Deprecation notice
These options still work, but Peach Payments strongly recommends that you use the updated options. Peach Payments intends to only add new features to the updated options.
Deprecated certain options in favour of new, more flexible options. The following sections describe the changes and how to migrate.
Event handling
Deprecated the events
property in favour of eventHandlers
:
// Deprecated
{
events: {
onCompleted: (event) => {
/* ... */
};
}
}
// Use this instead
{
eventHandlers: {
onCompleted: (event) => {
/* ... */
};
}
}
User interface customisation
Moved all user interface customisation options from options
to the new customisations
property:
// Deprecated
{
options: {
theme: { /* ... */ },
enableCancelButton: false,
enableAmountField: false,
enableCardBrandDisplay: false
}
}
// Use this instead
{
customisations: {
theme: { /* ... */ },
showCancelButton: false,
showAmountField: false,
showCardBrandDisplay: false
}
}
This table provides a complete mapping of deprecated options to their new equivalents:
Deprecated option | New option | Notes |
---|---|---|
options.theme | customisations.theme | Theme configuration remains the same |
options.enableCancelButton | customisations.showCancelButton | Renamed for clarity |
options.enableAmountField | customisations.showAmountField | Renamed for clarity |
options.enableCardBrandDisplay | customisations.showCardBrandDisplay | Renamed for clarity |
The new customisations
property also includes extra features not available in the deprecated options, such as card-specific customisations.
Updated 6 days ago