> For the complete documentation index, see [llms.txt](https://developer.esw.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.esw.com/global-checkout/embedded-checkout/direct-integration.md). # Direct Integration ### IFrame-based Embedded Checkout * The retailer needs to embed an irame on a dedicated page (e.g., /checkout). This iframe will host the checkout experience. * Script Injection: A script must be injected into the \ section of the retailer’s page. This script, hosted on a CDN, facilitates communication between the retailer’s site and the checkout iframe. ### Event-based Communication * The script listens for events like iframe-ready and iframe-height-update, ensuring dynamic height adjustments. * The retailer needs to handle build-checkout and begin-checkout events to fetch and assign the checkout URL to the iframe. * Pre-order URL Handling: Before rendering the iframe, the retailer must generate a pre-order URL by calling the checkout API and then pass this URL via an event. ### Domain Masking Requirement * The iframe must have the same domain as the retailer’s site to meet security and compliance standards. * X-Frame options and security headers need to be configured to prevent clickjacking. * A domain masking solution using TLS and CDN certificates ensures seamless integration. * Generic Public Script: A script hosted on the retailer’s CDN will be available for all tenants. This script simplifies the integration process by automatically handling iframe rendering and event communication. *** ### Steps #### 1. Set Up the Dedicated Checkout Page * The checkout should be a separate page (e.g., /checkout). * The entire page should be occupied by the checkout iframe. #### 2. Inject the Required Script * The CDN-hosted script is responsible for rendering the checkout iframe. * Include the script in the \ of the checkout page. #### 3. Generate the Pre-Order URL Before the checkout iframe is rendered, the retailer must: 1. Call the checkout API to generate a pre-order URL. 2. Send a "build checkout" event with the URL. #### 4. Render the Checkout Iframe Once the pre-order URL is obtained, trigger the event to embed the iframe. #### 5. Handle Events for Iframe Communication The embedded checkout script sends events to the retailer’s page. ### Events to Handle: * build-checkout: an event that needs to be emitted from the retailer's storefront to bootstrap checkout embedding. This event requires the checkout URL to be sent and set as iframe data. * iframe-ready : an event emitted by the script once the iframe is loaded. It notifies child iframes about the storefront’s origin, which should be used for secure communication. * esw-navigate-outside: an event emitted by the checkout in case external navigation needs to be done. Contains an external URL that the storefront should navigate to. * Other communication events, from checkout itself or payment panel as an inner iframe, are captured and proxied by script back to their consumers as contentWindow so it keeps the existing communication mechanism. * esw-update-iframe-height: an event to notify the size of the iframe height to avoid the use of scroll bars. * esw-scroll-to-error: an event to notify the origin that the view should be scrolled. It triggers once the checkout form contains invalid controls. It accepts ScrollToOptions that defines top and left dimensions. ### iFrame Communication Script * The iframe sends events (iframe-ready, esw-update-iframe-height, navigate-outside) to the parent page. * The parent page listens and responds (e.g., adjusting iframe height, redirecting users). * The iframe-communication.js script ensures seamless interaction. `` indicates that a separate script handles communication between the iframe and the parent page. ### Security & Domain Masking Setup #### Why This Matters * The iframe must have the same domain as the parent page (or use domain masking). * Proper security headers protect against clickjacking and unauthorized embedding. ### Steps for Domain Masking 1. Obtain a TLS Certificate for checkout.retailer.com. 2. Configure a CNAME Record e.g., checkout.retailer.com → checkout-service.provider.net 3. Ensure API endpoints match the retailer’s domain: {% hint style="info" %} e.g., {% endhint %} 4. Update security headers For more information, refer to [Domain Masking Configuration](/global-checkout/domain-masking.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developer.esw.com/global-checkout/embedded-checkout/direct-integration.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.