Embedded Checkout

Overview

Embedded Checkout enables you to embed a checkout on your website to accept payments without redirecting to a payment gateway.

Embedded Checkout has the following benefits over Redirect-based Checkout:

  • Better user experience and less security concerns: Keeping the customer on your website when checking out makes the experience seamless and allays security concerns.
  • Theming: Customise parts of the payment experience to match your branding.
  • Custom payment method ordering: Order payment methods according to your preferences.
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.

API endpoints

The API endpoints for the live and sandbox servers are:

ServiceLiveSandbox
Authenticationhttps://dashboard.peachpayments.comhttps://sandbox-dashboard.peachpayments.com
Checkouthttps://secure.peachpayments.comhttps://testsecure.peachpayments.com
Embedded Checkouthttps://checkout.peachpayments.com/js/checkout.jshttps://sandbox-checkout.peachpayments.com/js/checkout.js

Customisations

OptionTypeTargetDescription
options.orderingRecord<string, number>CheckoutCustom ordering of payment methods
options.paymentMethods.includestring[]CheckoutInclude specific payment methods
options.paymentMethods.excludestring[]CheckoutExclude specific payment methods
customisations.showCancelButtonbooleanCheckoutControls visibility of the cancel button
customisations.showAmountFieldbooleanCheckoutControls visibility of the amount field
customisations.theme.fontFamilystringCheckoutCustom font family (supports web safe or Google fonts)
customisations.theme.brand.primarystringCheckoutPrimary brand colour
customisations.theme.brand.secondarystringCheckoutSecondary brand colour (unused)
customisations.theme.cards.backgroundstringCheckoutCard background colour
customisations.theme.cards.backgroundHoverstringCheckoutCard hover background colour
customisations.card.showCardIconbooleanCard formControls visibility of the card icon
customisations.card.headingTextstringCard formText to show above the card payment in a heading
customisations.showCardBrandDisplaybooleanCard formControls visibility of the card brand display
customisations.card.brandsstring[]Card formList of card brands to show and accept
customisations.card.submitButtonTextstringCard formText to display on the submit button
eventHandlers.onCompletedfunctionCheckoutEvent handler fired when Checkout completes successfully
eventHandlers.onCancelledfunctionCheckoutEvent handler fired when the user cancels Checkout
eventHandlers.onExpiredfunctionCheckoutEvent handler fired when Checkout times out
eventHandlers.onBeforePaymentfunctionCheckoutEvent handler fired just before submission of a payment (can block payment)

Known limitations

Apple Pay

To accept Apple Pay on Embedded Checkout:

  1. Download the file hosted at https://secure.peachpayments.com/.well-known/apple-developer-merchantid-domain-association.
  2. Remove the .txt extension and host the file on the root of your own website's domain. For example, if your website is https://www.example.com/, host the file at https://www.example.com/.well-known/apple-developer-merchantid-domain-association.

    🚧

    • Including the .txt extension causes the activation of Apple Pay to fail.
    • The file must respond with a 200 HTTP status code and not any other HTTP status code (including redirect status codes like 301, 302, and so on).
  3. Request that Peach Payments support activate Apple Pay.

Quick links

📝 API playground

Detailed reference to the Embedded Checkout API endpoint and mock calls.

API reference
📝 SDK reference

Detailed reference to all the SDK functionality.

SDK reference
🚀 Postman collection

Use the sample Embedded Checkout (v2) calls in Postman. See the collection overview for more information.

Run in Postman
📋 Sample project

Experiment with an Embedded Checkout sample integration project.

Node sample project
Python sample project