{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-guides/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Inline Checkout Custom Layouts | xMoney Documentation","description":"Compose custom inline checkout layouts with xMoney paymentCard, Apple Pay, Google Pay, capability checks, manual submit, and runtime updates.","llmstxt":{"hide":false,"title":"xMoney Documentation","description":"Guides and API references for integrating xMoney card and crypto payments.","sections":[{"title":"Guides","description":"Integration guides for card payments, crypto, checkout, and dashboard.","includeFiles":["guides/**/*.md"],"excludeFiles":[]},{"title":"Card API","description":"REST API reference and concepts for xMoney card payments.","includeFiles":["api/**/*.md","api/**/*.yaml"],"excludeFiles":[]},{"title":"Crypto API","description":"REST API reference and concepts for xMoney crypto payments.","includeFiles":["crypto_api/**/*.md","crypto_api/**/*.yaml"],"excludeFiles":[]},{"title":"Card Issuing API","description":"Guides and API reference for xMoney whitelabel card issuing partners.","includeFiles":["card_issuing_api/**/*.md","card_issuing_api/**/*.yaml"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"custom-layouts","__idx":0},"children":["Custom Layouts"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use custom layouts when the full ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["XMoney.paymentForm()"]}," component is too prescriptive for your checkout page. You can mount the card form, Apple Pay button, and Google Pay button separately while keeping card data and wallet processing inside xMoney's secure iframe flow."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For the quickest integration, start with ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/checkout/inline-checkout/web-integration"},"children":["Website integration"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"choose-the-right-component","__idx":1},"children":["Choose the right component"]},{"$$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":"SDK method"},"children":["SDK method"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Use it for"},"children":["Use it for"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["XMoney.paymentForm()"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["One embedded form that can include card, saved cards, Apple Pay, and Google Pay."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["XMoney.paymentCard()"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Card-only checkout inside your own page layout."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["XMoney.applePay()"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Standalone Apple Pay button."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["XMoney.googlePay()"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Standalone Google Pay button."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["XMoney.getPaymentMethodCapabilities()"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Device and browser support checks before rendering wallet buttons."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All visual components require a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["container"]},". ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["savedCardPayment()"]}," is headless and is covered in ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/checkout/inline-checkout/saved-cards"},"children":["Saved cards"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"example-layout","__idx":2},"children":["Example layout"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create containers for each payment method that you want to mount."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"html","header":{"controls":{"copy":{}}},"source":"
\n
\n
\n
\n
\n\n
\n
\n \n
\n
\n","lang":"html"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Then share the order configuration and callbacks across widgets."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"const baseConfig = {\n publicKey,\n orderPayload,\n orderChecksum,\n options: {\n locale: 'en-US',\n enableBackgroundRefresh: true,\n appearance: {\n theme: 'custom',\n variables: {\n colorPrimary: '#0d9488',\n borderRadius: '10px',\n },\n },\n },\n onReady() {\n console.log('xMoney widget ready')\n },\n onPaymentProcessing(isProcessing) {\n updateCheckoutLoading(isProcessing)\n },\n onPaymentComplete(transaction) {\n handlePaymentResult(transaction)\n },\n onError(error) {\n showPaymentError(error?.message || 'Payment could not be started')\n },\n}\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"check-wallet-capabilities","__idx":3},"children":["Check wallet capabilities"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Apple Pay and Google Pay availability depends on device, browser, account setup, and wallet readiness. Check capabilities before creating standalone wallet widgets."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"const capabilities = await window.XMoney.getPaymentMethodCapabilities()\n\nif (!capabilities.applePay.supported) {\n document.getElementById('apple-pay').hidden = true\n}\n\nif (!capabilities.googlePay.supported) {\n document.getElementById('google-pay').hidden = true\n}\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The SDK returns a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reason"]}," when a wallet is unavailable. Use that for diagnostics, not for shopper-facing copy."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"mount-standalone-wallets","__idx":4},"children":["Mount standalone wallets"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"const widgets = []\n\nif (capabilities.applePay.supported) {\n const applePay = await window.XMoney.applePay({\n ...baseConfig,\n container: 'apple-pay',\n options: {\n ...baseConfig.options,\n appearance: {\n style: 'black',\n type: 'pay',\n radius: 8,\n },\n },\n })\n\n widgets.push(applePay)\n}\n\nif (capabilities.googlePay.supported) {\n const googlePay = await window.XMoney.googlePay({\n ...baseConfig,\n container: 'google-pay',\n options: {\n ...baseConfig.options,\n appearance: {\n color: 'black',\n type: 'pay',\n borderType: 'no_border',\n radius: 8,\n },\n },\n })\n\n widgets.push(googlePay)\n}\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Wallet widgets handle their own button click, wallet sheet, payment submission, 3DS behavior, and result callback."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"mount-a-card-only-component","__idx":5},"children":["Mount a card-only component"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentCard()"]}," renders only the card and saved-card UI. It removes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentMethods"]}," from the config, so mount Apple Pay and Google Pay separately if you want wallet buttons."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"const card = await window.XMoney.paymentCard({\n ...baseConfig,\n container: 'payment-card',\n card: {\n validationMode: 'onChange',\n savedCards: {\n enabled: true,\n optInVisible: true,\n },\n submitButton: {\n visible: false,\n type: 'pay',\n },\n },\n})\n\nwidgets.push(card)\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"submit-and-validate-manually","__idx":6},"children":["Submit and validate manually"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Hide the built-in submit button when your page has its own checkout button. Call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validate()"]}," before ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["submit()"]}," if you want to control the button state or display a custom error summary."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"document.getElementById('pay-button').addEventListener('click', async () => {\n const { isValid, errors } = await card.validate()\n\n if (!isValid) {\n renderValidationErrors(errors)\n return\n }\n\n card.submit()\n})\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["submit()"]}," starts the payment flow. Watch ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onPaymentProcessing"]}," to disable your button while the SDK is working."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"runtime-updates","__idx":7},"children":["Runtime updates"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All visual widgets support order updates. Use this when totals change."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"async function updateAllWidgets(nextOrder) {\n const { orderPayload, orderChecksum } = await createCheckoutIntent(nextOrder)\n\n await Promise.all(\n widgets.map((widget) =>\n widget.updateOrder({\n orderPayload,\n orderChecksum,\n })\n )\n )\n}\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Card widgets also support locale and appearance updates."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"card.updateLocale('ro-RO')\n\ncard.updateAppearance({\n theme: 'dark',\n variables: {\n colorPrimary: '#38bdf8',\n },\n})\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"cleanup","__idx":8},"children":["Cleanup"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Destroy every mounted widget before leaving the checkout page."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"function destroyCheckout() {\n widgets.forEach((widget) => widget.destroy())\n widgets.length = 0\n}\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This removes iframes, message listeners, overlays, and any active 3DS modal."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"related-guides","__idx":9},"children":["Related guides"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/checkout/inline-checkout/web-integration"},"children":["Website integration"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/checkout/inline-checkout/saved-cards"},"children":["Saved cards"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/checkout/inline-checkout/3ds-results"},"children":["3DS and payment results"]}]}]}]},"headings":[{"value":"Custom Layouts","id":"custom-layouts","depth":1},{"value":"Choose the right component","id":"choose-the-right-component","depth":2},{"value":"Example layout","id":"example-layout","depth":2},{"value":"Check wallet capabilities","id":"check-wallet-capabilities","depth":2},{"value":"Mount standalone wallets","id":"mount-standalone-wallets","depth":2},{"value":"Mount a card-only component","id":"mount-a-card-only-component","depth":2},{"value":"Submit and validate manually","id":"submit-and-validate-manually","depth":2},{"value":"Runtime updates","id":"runtime-updates","depth":2},{"value":"Cleanup","id":"cleanup","depth":2},{"value":"Related guides","id":"related-guides","depth":2}],"frontmatter":{"seo":{"title":"Inline Checkout Custom Layouts | xMoney Documentation","description":"Compose custom inline checkout layouts with xMoney paymentCard, Apple Pay, Google Pay, capability checks, manual submit, and runtime updates."}},"lastModified":"2026-06-19T09:28:44.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/checkout/inline-checkout/custom-layouts","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}