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.
API endpoints
The API endpoints for the live and sandbox servers are:
Service | Live | Sandbox |
---|---|---|
Authentication | https://dashboard.peachpayments.com | https://sandbox-dashboard.peachpayments.com |
Checkout | https://secure.peachpayments.com | https://testsecure.peachpayments.com |
Embedded Checkout | https://checkout.peachpayments.com/js/checkout.js | https://sandbox-checkout.peachpayments.com/js/checkout.js |
Customisations
Option | Type | Target | Description |
---|---|---|---|
options.ordering | Record<string, number> | Checkout | Custom ordering of payment methods |
options.paymentMethods.include | string[] | Checkout | Include specific payment methods |
options.paymentMethods.exclude | string[] | Checkout | Exclude specific payment methods |
customisations.showCancelButton | boolean | Checkout | Controls visibility of the cancel button |
customisations.showAmountField | boolean | Checkout | Controls visibility of the amount field |
customisations.theme.fontFamily | string | Checkout | Custom font family (supports web safe or Google fonts) |
customisations.theme.brand.primary | string | Checkout | Primary brand colour |
customisations.theme.brand.secondary | string | Checkout | Secondary brand colour (unused) |
customisations.theme.cards.background | string | Checkout | Card background colour |
customisations.theme.cards.backgroundHover | string | Checkout | Card hover background colour |
customisations.card.showCardIcon | boolean | Card form | Controls visibility of the card icon |
customisations.card.headingText | string | Card form | Text to show above the card payment in a heading |
customisations.showCardBrandDisplay | boolean | Card form | Controls visibility of the card brand display |
customisations.card.brands | string[] | Card form | List of card brands to show and accept |
customisations.card.submitButtonText | string | Card form | Text to display on the submit button |
eventHandlers.onCompleted | function | Checkout | Event handler fired when Checkout completes successfully |
eventHandlers.onCancelled | function | Checkout | Event handler fired when the user cancels Checkout |
eventHandlers.onExpired | function | Checkout | Event handler fired when Checkout times out |
eventHandlers.onBeforePayment | function | Checkout | Event handler fired just before submission of a payment (can block payment) |
Known limitations
- Embedded Checkout does not support PayPal.
- The secondary brand theme colour is not used.
Apple Pay
To accept Apple Pay on Embedded Checkout:
- Download the file hosted at https://secure.peachpayments.com/.well-known/apple-developer-merchantid-domain-association.
- Remove the
.txt
extension and host the file on the root of your own website's domain. For example, if your website ishttps://www.example.com/
, host the file athttps://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).
- Including the
- 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. | 📋 Sample project Experiment with an Embedded Checkout sample integration project. Node sample project Python sample project |
Updated 20 days ago