{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-guides/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Inline Checkout 3DS and Payment Results | xMoney Documentation","description":"Handle 3D Secure authentication, background transaction refresh, callbacks, and final payment reconciliation with xMoney inline checkout.","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":"3ds-and-payment-results","__idx":0},"children":["3DS and Payment Results"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Inline Checkout keeps most 3D Secure and payment-result handling inside the SDK. Your page listens to callbacks, updates the shopper experience, and confirms the final transaction status on the backend."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"default-behavior","__idx":1},"children":["Default behavior"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["By default, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["options.enableBackgroundRefresh"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"await window.XMoney.paymentForm({\n  container: 'xmoney-payment-form',\n  publicKey,\n  orderPayload,\n  orderChecksum,\n  options: {\n    enableBackgroundRefresh: true,\n  },\n  onPaymentProcessing(isProcessing) {\n    setLoading(isProcessing)\n  },\n  onPaymentComplete(transaction) {\n    handlePaymentResult(transaction)\n  },\n  onError(error) {\n    showPaymentError(error)\n  },\n})\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["With background refresh enabled:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The SDK submits the payment inside the secure iframe."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If 3DS is required, the SDK opens the authentication flow in a modal."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The secure iframe polls the transaction result in the background."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The SDK calls ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onPaymentComplete(transaction)"]}," when the transaction reaches a complete status."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The SDK destroys the widget after ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onPaymentComplete"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is the recommended behavior for most website and WebView integrations."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"content-security-policy-for-embedded-3ds","__idx":2},"children":["Content Security Policy for embedded 3DS"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If your checkout page sends a Content Security Policy, make sure it allows the SDK's iframe-based 3DS modal to load external 3DS pages."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["3DS authentication can navigate through xMoney Secure, payment provider pages, directory servers, and card issuer ACS pages. Issuer and ACS hostnames vary by card, region, and provider configuration, so a fixed allowlist that contains only xMoney domains can block valid challenges."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For iframe-based 3DS, your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["frame-src"]}," policy should allow HTTPS frame destinations:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"Content-Security-Policy: frame-src 'self' https:;\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you already use a stricter policy, keep your existing trusted frame sources and add ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https:"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["frame-src"]},". For older browser coverage, mirror the same value in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["child-src"]}," if your CSP uses that directive."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Do not use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["frame-ancestors"]}," for this requirement. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["frame-ancestors"]}," controls who can embed your page, while ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["frame-src"]}," controls what your checkout page may embed."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Do not restrict 3DS frames to xMoney only"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["During a 3DS challenge, the modal iframe may need to render a provider or issuer-controlled page such as an ACS URL. If ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["frame-src"]}," only allows xMoney domains, the browser can block the challenge before the shopper can authenticate."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"callback-responsibilities","__idx":3},"children":["Callback responsibilities"]},{"$$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":"Callback"},"children":["Callback"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"When it fires"},"children":["When it fires"]},{"$$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":["onReady()"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The iframe has loaded and initialized."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Enable the checkout UI."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onPaymentProcessing(isProcessing)"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The SDK starts or stops payment work."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Disable buttons, show loaders, prevent duplicate submission."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onPaymentComplete(transaction)"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The final transaction status is available to the iframe."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Route the shopper to a result state and ask your backend to confirm the order."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError(error)"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Initialization, configuration, network, or polling errors occur."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Show retry guidance and log diagnostics."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onPaymentComplete"]}," can include successful and failed results. Inspect ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction.transactionStatus"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"function handlePaymentResult(transaction) {\n  switch (transaction.transactionStatus) {\n    case 'complete-ok':\n      window.location.href = `/checkout/success?orderId=${transaction.externalOrderId}`\n      break\n    case 'complete-failed':\n      showPaymentError('Payment failed. Please try another payment method.')\n      break\n    default:\n      showPaymentPending('Payment submitted. We are confirming the final status.')\n  }\n}\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"server-side-confirmation","__idx":4},"children":["Server-side confirmation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Browser callbacks are useful for the user experience, but fulfillment should depend on trusted server-side data."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use one of these server-side confirmation paths:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Handle the xMoney webhook or IPN for the final transaction."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Query the transaction status from your backend before fulfilling the order."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Store the xMoney ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionId"]},", your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["orderId"]},", and the final status together for reconciliation."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Do not fulfill from client callbacks only"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The browser can be closed, refreshed, blocked by extensions, or tampered with. Always confirm the final transaction result from your backend before releasing goods or services."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"redirect-fallback","__idx":5},"children":["Redirect fallback"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["enableBackgroundRefresh"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]},", the SDK no longer waits for the final result in the background."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"await window.XMoney.paymentForm({\n  container: 'xmoney-payment-form',\n  publicKey,\n  orderPayload,\n  orderChecksum,\n  options: {\n    enableBackgroundRefresh: false,\n  },\n})\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["With this mode:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If 3DS is required, the SDK opens the 3DS modal."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If no modal flow is required, the parent page can be redirected to the returned URL."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["backUrl"]}," and backend result page become responsible for the final shopper experience."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use this only when your checkout flow is designed around redirects. For most inline checkout pages, keep background refresh enabled."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"handling-retries","__idx":6},"children":["Handling retries"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A failed transaction should usually create a new order payload and checksum before retrying. This ensures the SDK starts with fresh signed order data."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"async function retryPayment() {\n  paymentForm?.destroy()\n\n  const nextIntent = await createCheckoutIntent()\n\n  paymentForm = await window.XMoney.paymentForm({\n    container: 'xmoney-payment-form',\n    publicKey: nextIntent.publicKey,\n    orderPayload: nextIntent.orderPayload,\n    orderChecksum: nextIntent.orderChecksum,\n    onPaymentComplete: handlePaymentResult,\n    onError: showPaymentError,\n  })\n}\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"webview-considerations","__idx":7},"children":["WebView considerations"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In mobile WebViews, 3DS can send the app to another app or browser context temporarily. Preserve the checkout page state so the flow can continue when the app returns to the foreground."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Recommended behavior:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Keep ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["enableBackgroundRefresh"]}," enabled."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Do not destroy the WebView while a payment is processing."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Preserve the checkout URL and signed payload across app backgrounding."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Let the SDK complete the modal or result polling before closing the WebView."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/checkout/inline-checkout/mobile-webview"},"children":["Mobile WebView integration"]}," for platform guidance."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"related-guides","__idx":8},"children":["Related guides"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/payments/3d-secure/3ds-redirects"},"children":["3D Secure redirects"]}]},{"$$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/mobile-webview"},"children":["Mobile WebView integration"]}]}]}]},"headings":[{"value":"3DS and Payment Results","id":"3ds-and-payment-results","depth":1},{"value":"Default behavior","id":"default-behavior","depth":2},{"value":"Content Security Policy for embedded 3DS","id":"content-security-policy-for-embedded-3ds","depth":2},{"value":"Callback responsibilities","id":"callback-responsibilities","depth":2},{"value":"Server-side confirmation","id":"server-side-confirmation","depth":2},{"value":"Redirect fallback","id":"redirect-fallback","depth":2},{"value":"Handling retries","id":"handling-retries","depth":2},{"value":"WebView considerations","id":"webview-considerations","depth":2},{"value":"Related guides","id":"related-guides","depth":2}],"frontmatter":{"seo":{"title":"Inline Checkout 3DS and Payment Results | xMoney Documentation","description":"Handle 3D Secure authentication, background transaction refresh, callbacks, and final payment reconciliation with xMoney inline checkout."}},"lastModified":"2026-06-22T14:41:01.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/checkout/inline-checkout/3ds-results","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}