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:

EventDescription
onCompletedThe customer completes a payment and the checkout experience.
onCancelledThe customer cancels the checkout experience.
onExpiredThe checkout experience expires (customers have 30 minutes to complete a payment).
onBeforePaymentFired 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.

    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.

    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.

    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.

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.)
Embedded Checkout with the cancel button and amount removed.

Embedded Checkout with the cancel button and amount removed.

Card payment form with the amount and card brand field 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 optionNew optionNotes
options.themecustomisations.themeTheme configuration remains the same
options.enableCancelButtoncustomisations.showCancelButtonRenamed for clarity
options.enableAmountFieldcustomisations.showAmountFieldRenamed for clarity
options.enableCardBrandDisplaycustomisations.showCardBrandDisplayRenamed for clarity

The new customisations property also includes extra features not available in the deprecated options, such as card-specific customisations.


Did this page help you?