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>;
/**
* Configure which payment methods (https://developer.peachpayments.com/docs/pp-payment-methods#south-africa) are shown to the customer without making changes to your Peach Payments account configuration.
*
* Although you can specify both `include` and `exclude` at the same time, it's more likely you'd want to do one or the other.
*
* @example
* {
* include: ["CARD", "MOBICRED"],
* exclude: ["PAYFLEX"],
* }
*/
paymentMethods?: {
/**
* Include specific payment methods.
*/
include?: string[];
/**
* Exclude specific payment methods.
*/
exclude?: string[];
};
};
/**
* 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?: {
/**
* Supports web safe or Google fonts, for example, `TIMES NEW ROMAN`, `MONOSPACE`, and so on.
*/
fontFamily?: string;
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;
/**
* List of card brands to show, enabling you to disable and hide card brands without having to change your Peach Payments account configuration.
* For example, if you are configured for Visa, Mastercard, and Amex, but only want to show and accept Visa, you can do that without having to change your Peach Payments account configuration.
*
* If you do not provide any brands (or provide invalid brands), all brands show.
*
* @default all brands - ["VISA", "MASTERCARD", "AMERICAN EXPRESS", "DINERS CLUB"]
*/
brands?: 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
Colours
Embedded Checkout enables you to set the following colours:
-
Brand primary: Controls the cancel button font and border hover colour, the currency font colour, the payment method card border hover colour, and the payment methods' submit buttons (Pay Now for card payments and Verify, Redeem, or Sign in for selected alternative payment methods) colour.
Embedded Checkout with primary colour set to orange.
Pay Now button 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;
};
};
Font
Embedded Checkout enables you to set the font to a web safe or Google font (Times New Roman, Monospace, and so on), which affects the currency, amount, cancel button, payment method names, footer, and payment method text elements.
- Apple Pay, Google Pay, and Samsung Pay buttons are logos and are not affected by font changes.
- The CVV and card number fields do not support certain fonts.

Embedded Checkout with the Monospace font.
type Theme = {
fontFamily?: string;
};
Customise payment method availability and order
Embedded Checkout enables you to specify:
- Which payment methods to show to customers.
- 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.
options?: {
ordering?: {
MASTERPASS: 1;
"1FORYOU": 2;
MOBICRED: 3;
MOBICRED: 4;
};
paymentMethods?: {
include: ["MASTERPASS", "1FORYOU", "MOBICRED", "CARD"],
exclude: ["PAYFLEX"],
};
}
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: shown)
- Custom heading text (default:
Please enter your card details below to complete the payment.
) - Show or hide card brands (default: all brands)
- Custom submit button text (default:

Embedded Checkout with the cancel button and amount removed.

Embedded Checkout with all card brands except Visa 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;
brands?: 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 11 days ago