Tutorial

📘

The Embedded Checkout sample projects for Node and Python enable you to experiment with Embedded Checkout and produce a working prototype with minimal changes.

To support Apple Pay on Embedded Checkout, follow these instructions.

The authentication service URL and other service URLs are available in the API endpoints section.

Follow these instructions to embed checkout in your website:

Generate an access token by executing a POST {peach-auth-service}/api/oauth/token request with your client ID, client secret, and merchant ID.

curl --location --request POST '{peach-auth-service}/api/oauth/token' 
--header 'content-type: application/json' 
--data-raw 
'{
    "clientId": "{clientId}",
    "clientSecret": "{clientSecret}",
    "merchantId": "{merchantId}"
}'

Create a checkout instance by executing a POST {checkout-endpoint}/v2/checkout request with the JWT retrieved from the above call.
📘
Embedded Checkout:
- Requires a unique nonce for each request made to the /v2/checkout endpoint.
- Requires that you allowlist URL domains that execute the API POST request to Checkout for added security.
- Can tokenise cards.
Create the payment form by including the script tag on your HTML page.
🚧
- If your website uses a Content Security Policy (CSP), you must add the required directives from the Embedded Checkout CSP directives list to your policy.
  - You must set a height for the element with the checkout-root ID:
    
    Minimum: 640 pixels
    
    Fill the container: 100%
    
    Only element on the page: 100vh to fill the screen height
```
<html>
<head>
</head>
<body>
<div id="payment-form"></div>
<script src="https://sandbox-checkout.peachpayments.com/js/checkout.js"></script>
</body>
```
Ensure that the checkout script from step 3 is fully loaded and then instantiate Embedded Checkout using your entity ID and the checkout ID.

❗
If the script is not fully loaded, your customers might receive Checkout not found errors and be unable to pay.
```
<script>
  const checkout = Checkout.initiate({
    key: <entity id>,
    checkoutId: <Checkout Id>,
 });

  checkout.render("#payment-form");
</script>
```

Get the status of the checkout from Embedded Checkout events.

const checkout = Checkout.initiate({
  key: <entity id>,
  checkoutId: <Checkout Id>,
  events: {
    onCompleted: (event) => console.log(event),
    onCancelled: (event) => console.log(event),
    onExpired: (event) => console.log(event),
  },
});

Theme Embedded Checkout.

const checkout = Checkout.initiate({
  key: "<entity id>",
  checkoutId: "<Checkout Id>",
  options: {
    theme: {
      brand: {
        primary: "#ff0000",
      },
      cards: {
        background: "#00ff00",
        backgroundHover: "#F3F3F4",
      }
    },
  },
});

Customise the availability and order of payment methods.

const checkout = Checkout.initiate({
  key: "<entity id>",
  checkoutId: "<Checkout Id>",
  options: {
    ordering: {
      PAYFLEX: 1,
      CARD: 2,
    },
  },
});

Consolidated example snippet

The following snippet provides an example of the complete HTML page:

<html>
  <head> </head>
  <body>
    <div id="payment-form"></div>
    <script src="https://sandbox-checkout.peachpayments.com/js/checkout.js"></script>

    <script>
      const checkout = Checkout.initiate({
        key: "{entityId}",
        checkoutId: "{checkoutId}",
        options: {
          theme: {
            brand: {
              primary: "#ff0000",
            },
            cards: {
              background: "#00ff00",
              backgroundHover: "#F3F3F4",
            },
          },
        },
      });

      checkout.render("#payment-form");
    </script>
  </body>
</html>

🚧
Running the local HTML page in your browser only renders the Checkout instance; you can view the payment methods but cannot attempt a payment. To attempt a payment, you must host the HTML page.
One way to do this locally is by using Python's http.server functionality, for example, by executing python -m http.server 8000 from the HTML file's directory, and then opening http://localhost:8000/file.html in your browser.

Embedded Express

Embedded Express is a wallet-only variant of Embedded Checkout that displays Apple Pay, Google Pay, and Samsung Pay only. Use Embedded Express to offer a quick, one-click payment experience directly on a product page or any other location where you want to surface wallet payment methods without the full Checkout user interface.

🚧

To accept wallet payments through Embedded Express, ensure that your Peach Payments account includes support for Apple Pay, Google Pay, and Samsung Pay, or whichever wallets you want to offer.

Embedded Express does not support Apple Pay or Samsung Pay on all devices or browsers.

Customers who want to pay with a different payment method can still navigate to the full Embedded Checkout from the same checkout instance.

When to use Embedded Express

Use Embedded Express when you want to:

Embed wallet payment methods on a product page, cart preview, or other high-intent location to reduce the steps to purchase.
Increase conversion by offering one-click payment for customers who have already set up a wallet on their device.
Continue to offer non-wallet payment methods through the full Embedded Checkout experience as a fallback.

Use Embedded Checkout when you want to show the complete set of configured payment methods in a single embedded experience.

Enable Embedded Express

Embedded Express uses the same authentication, checkout creation, and rendering flow as Embedded Checkout. To enable Embedded Express, call Checkout.express instead of Checkout.initiate when instantiating the Checkout object.

See the SDK reference for details on which options Embedded Express supports. Embedded Express does not support any customisations, aside from the event handlers.

Replace the standard Embedded Checkout instantiation:

const checkout = Checkout.initiate({
  key: "<entity id>",
  checkoutId: "<Checkout Id>",
});

checkout.render("#payment-form");

With the Embedded Express instantiation:

const checkout = Checkout.express({
  key: "<entity id>",
  checkoutId: "<Checkout Id>",
});

checkout.render("#payment-form");