This document lists common integration issues encountered with Kustom Checkout (KCO), categorized by frequency. It's not an exhaustive list but a summary of key problems observed.
Do not re-initialize KCO without reloading the page. Use the suspend/resume method instead for order updates. Re-initialization prevents cleanup of listeners and iframes, leading to errors.
Ensure the Kustom Checkout snippet, obtained from the backend, is injected into the main page/frame. Failure to do so can cause UI/UX and functionality issues.
Re-creating or detaching iframes from the DOM can disrupt message passing between iframes, causing issues. Important information is passed via iframe URLs.
Avoid modifying built-in browser functions, particularly with older libraries like Prototype.js. Directly modifying these functions can cause Kustom Checkout to malfunction. Use local functions if necessary to replicate browser functionality.
Kustom Checkout iframes use inline styles, which have high specificity. Merchants should avoid applying global styles to all iframes, especially using !important, as this can conflict with Kustom's styles and prevent full functionality.
Modifying the iframe URLs used by Kustom Checkout can break the parsing of important information.
Applying the transform property to the body element can disrupt the positioning of the fullscreen iframe, causing issues with viewport coverage and content visibility.
If a payment method that uses a popup (for example, Klarna) opens both a popup window and an in-page view at the same time, your page is sending the header Cross-Origin-Opener-Policy: same-origin. Because Kustom Checkout runs on a different domain, that header cuts the popup off from the page.
On any page that renders the checkout snippet, set the header to same-origin-allow-popups instead of same-origin.