{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-products/hosted-checkout/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Embedded Checkout (iFrame) — Web Implementation","description":"Official Banxa API documentation – on-ramp and off-ramp transfers with identity verification and compliance.","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"embedded-checkout-iframe--web-implementation","__idx":0},"children":["Embedded Checkout (iFrame) — Web Implementation"]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"basic-implementation","__idx":1},"children":["Basic implementation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Load the iFrame inside a modal ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<div>"]}," in your application:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"html","header":{"controls":{"copy":{}}},"source":"<div class=\"checkout-modal\">\n  <iframe\n    src=\"CHECKOUT_URL\"\n    style=\"border:0; width: 100%; min-height: 80vh;\"\n    allow=\"payment; camera; microphone; encrypted-media\"\n    sandbox=\"allow-scripts allow-same-origin allow-forms allow-popups\"\n  ></iframe>\n</div>\n","lang":"html"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Replace ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CHECKOUT_URL"]}," with the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checkoutUrl"]}," from your order creation response, or your constructed referral URL."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"required-iframe-attributes","__idx":2},"children":["Required iframe attributes"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Attribute"},"children":["Attribute"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Value"},"children":["Value"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Purpose"},"children":["Purpose"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allow"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payment; camera; microphone; encrypted-media"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Permits camera access for KYC, payment APIs, and encrypted media"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sandbox"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allow-scripts allow-same-origin allow-forms allow-popups"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Allows the checkout to function correctly within the sandboxed context"]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"when-the-checkout-redirects-out-of-the-iframe","__idx":3},"children":["When the checkout redirects out of the iFrame"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In some scenarios the checkout will force a full redirect to the Banxa site rather than staying inside the iFrame:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["KYC required"]}," — if a customer needs to complete identity verification, they are redirected to Banxa to complete KYC (due to camera access limitations inside iFrames). On their next order, the checkout runs inside the iFrame as normal."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Apple Pay"]}," — Apple Pay requires merchant certificate and domain configuration to work inside an iFrame. Contact your Banxa account manager to ensure Apple Pay is correctly set up for your integration."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["iDEAL, Klarna, PayPal"]}," — these payment methods redirect the customer out of the iFrame to complete their payment. Afterwards, the customer is returned to the Banxa order status page and can then return to your site."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Safari / browsers without third-party cookie support"]}," — if the customer's browser blocks third-party cookies (default in Safari), the checkout cannot maintain its state in an iFrame and will redirect to the Banxa site to complete the order."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"permissions-policy","__idx":4},"children":["Permissions Policy"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If your page sets a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Permissions-Policy"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Feature-Policy"]}," header, ensure it does not restrict ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["camera"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["microphone"]}," for the iframe origin."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example CSP that allows Banxa:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"Permissions-Policy: camera=(\"https://checkout.banxa.com\"), microphone=(\"https://checkout.banxa.com\")\n"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"detecting-checkout-completion","__idx":5},"children":["Detecting checkout completion"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Monitor navigation by watching for your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redirectUrl"]}," in the iframe ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["src"]},". You can also listen for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["postMessage"]}," events from the checkout — validate the origin before processing any message."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"// Validate origin before processing any postMessage from the checkout\nwindow.addEventListener('message', (event) => {\n  if (event.origin !== 'https://checkout.banxa.com') return;\n  // Handle event.data as appropriate for your integration\n});\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"sizing","__idx":6},"children":["Sizing"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Banxa checkout is responsive. Minimum recommended dimensions:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Width: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["375px"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Height: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["600px"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For mobile breakpoints, consider showing the checkout as a full-screen modal overlay rather than an inline iframe."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"content-security-policy","__idx":7},"children":["Content Security Policy"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If your app uses a CSP, add Banxa to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["frame-src"]}," directive:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"Content-Security-Policy: frame-src https://checkout.banxa.com https://checkout.banxa-sandbox.com;\n"},"children":[]}]},"headings":[{"value":"Embedded Checkout (iFrame) — Web Implementation","id":"embedded-checkout-iframe--web-implementation","depth":1},{"value":"Basic implementation","id":"basic-implementation","depth":2},{"value":"Required iframe attributes","id":"required-iframe-attributes","depth":2},{"value":"When the checkout redirects out of the iFrame","id":"when-the-checkout-redirects-out-of-the-iframe","depth":2},{"value":"Permissions Policy","id":"permissions-policy","depth":2},{"value":"Detecting checkout completion","id":"detecting-checkout-completion","depth":2},{"value":"Sizing","id":"sizing","depth":2},{"value":"Content Security Policy","id":"content-security-policy","depth":2}],"frontmatter":{"title":"iFrame Checkout: Web Implementation | Banxa Docs","description":"Embed Banxa checkout in a web iFrame. Required allow attributes, Permissions Policy config, postMessage completion detection, CSP frame-src, and sizing guidance.","seo":{"title":"Embedded Checkout (iFrame) — Web Implementation"}},"lastModified":"2026-05-19T23:30:38.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/hosted-checkout/docs/checkout-experience/iframe/iframe-web","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}