WebsiteStatusSupport
Documentation
Sign up

Checkout plugins integration guidelines

Suggest Edits

Rendering payment method redirect URL on Checkout or e-commerce plugins

Peach Payments Checkout and e-commerce plugins render your payment method user interface inside an iframe. This process works as follows:

  1. After getting the response from the initial debit request to the payment service provider’s <https://{{payment-service-provider-host}}/v1/debit> endpoint, Peach Payments redirects to the redirect URL provided in the response.
  2. When the payment service provider’s redirect URL (Checkout user interface) is loaded in the iframe, it is expected to respond with an empty status to inform Peach Payments Checkout that the user interface has been initialized and is ready to be shown to the end user. All communication between Peach Payments Checkout and the payment service provider’s redirect URL (Checkout user interface) is done through postMessage. The partner-redirect event, which supports GET- and POST-based redirect methods, must be used to redirect the Checkout page to a URL.
  3. With the release of Embedded Checkout that can be hosted on merchants' websites, the checkoutOrigin is not necessarily tied to the Hosted Checkout domain.
    1. To support Embedded Checkout, Checkout (Hosted and Embedded) loads the payment service provider’s redirect URL with a URL fragment (#...) that is a Base64-encoded version of the origin domain.
    2. This can be used as the origin when performing postMessage calls to Checkout.
// Sandbox Checkout Origin URL: https://testsecure.peachpayments.com
// Live Checkout Origin URL: https://secure.peachpayments.com

// Use the URL fragment as the Checkout origin if it is set, otherwise fallback to previous approach
const checkoutOrigin = location.hash
	? atob(location.hash.substring(1))
	: "checkout_origin_url_for_respective_environment";

var messageDetails = {
  message: "push-checkout-events",
  events: [{
    type: "partner-redirect",
    url: "https://{{payment-service-provider-host}}/v1/debit",
    method: "POST", // Or "GET" body is ignored for "GET"
    body: {},
  }]
};
window.parent.postMessage(messageDetails, checkoutOrigin, []);

❗️

Nested Checkouts and recursive redirects

To avoid nested Checkouts and recursive redirects in your payments flow, you must use the partner-redirect event to redirect the Checkout page to a URL.

Failure to do so causes the redirect to only affect the iframe and not the whole site, which causes nested Checkouts to occur.

  1. When the user completes the payment, the payment service provider redirects the user to the shopperResultUrl provided in the debit request.

Sample live configuration

<html>
  <head>
    <title>My Payment Method Page</title>
  </head>
  <body>
    <h1>Complete your payment</h1>
    <form method="POST" action="complete" id="payForm">
      <button type="submit">Pay now</button>
    </form>
    <script>
      const checkoutOrigin = location.hash
      	? atob(location.hash.substring(1))
        : "https://secure.peachpayments.com";
      
      function post(events) {
        window.parent.postMessage(
          {
            message: "push-checkout-events",
            events: events
          },
          checkoutOrigin,
          []
        );
      }
      
      function inIframe () {
        try {
          return window.self !== window.top;
        } catch (e) {
          return true;
        }
      }

      // Condition to handle rendering of payment page in Peach Payments Checkout/E-Commerce Plugins
      if (inIframe()) {
        post([{ type:"status", value: undefined }]);
      }

      function submitForm(event) {
        // Only handle it specifically for iframe
        // otherwise the form post can handle it normally.
        if (inIframe()) {
          event.preventDefault();
          post([{ type: "partner-redirect", url: "<complete url>", method: "POST", body: {}}]);
        }
      }

      let payForm = document.getElementById("payForm");
      payForm.onsubmit = submitForm;
    </script>
  </body>
</html>

General user interface guidelines

The Checkout UI for the payment service provider should follow the guidelines described in Checkout Design System and Components for it to be rendered correctly on Peach Payments Checkout and e-commerce plugins.

Updated 2 months ago