{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-guides/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Inline Checkout in Mobile WebViews | xMoney Documentation","description":"Use the xMoney inline checkout SDK inside iOS and Android WebViews while preserving wallet, 3DS, and lifecycle behavior.","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"]},{"title":"Card API","description":"REST API reference and concepts for xMoney card payments.","includeFiles":["api/**/*.md","api/**/*.yaml"]},{"title":"Crypto API","description":"REST API reference and concepts for xMoney crypto payments.","includeFiles":["crypto_api/**/*.md","crypto_api/**/*.yaml"]},{"title":"Card Issuing API","description":"Guides and API reference for xMoney whitelabel card issuing partners.","includeFiles":["card_issuing_api/**/*.md","card_issuing_api/**/*.yaml"]}]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"mobile-webview-integration","__idx":0},"children":["Mobile WebView Integration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can use Inline Checkout inside a mobile app by loading a checkout web page in a WebView. The native app owns navigation, loading states, and lifecycle recovery, while xMoney's web SDK owns card collection, wallet orchestration, 3DS, and payment submission."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use this guide when your mobile app already has a web checkout page or when you want one shared checkout implementation for web, iOS, and Android."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For hosted checkout WebView flows, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/mobile-apps/accepting-payments"},"children":["Accepting Payments in Your Mobile App"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"recommended-architecture","__idx":1},"children":["Recommended architecture"]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"sequenceDiagram\n participant mobileApp as MobileApp\n participant checkoutPage as CheckoutWebPage\n participant merchantBackend as MerchantBackend\n participant xMoneySdk as XMoneySDK\n participant xMoneyApi as XMoneyAPI\n\n mobileApp->>checkoutPage: Open WebView checkout URL\n checkoutPage->>merchantBackend: Create inline checkout order\n merchantBackend-->>checkoutPage: publicKey, orderPayload, orderChecksum\n checkoutPage->>xMoneySdk: Mount paymentForm or custom widgets\n xMoneySdk->>xMoneyApi: Process card, wallet, or saved card payment\n alt Requires3DS\n xMoneySdk-->>mobileApp: WebView opens authentication flow\n end\n xMoneySdk-->>checkoutPage: onPaymentComplete or onError\n checkoutPage-->>mobileApp: Notify native shell of result state\n","diagramHtml":"XMoneyAPIXMoneySDKMerchantBackendCheckoutWebPageMobileAppXMoneyAPIXMoneySDKMerchantBackendCheckoutWebPageMobileAppalt[Requires3DS]Open WebView checkout URLCreate inline checkout orderpublicKey, orderPayload, orderChecksumMount paymentForm or custom widgetsProcess card, wallet, or saved card paymentWebView opens authentication flowonPaymentComplete or onErrorNotify native shell of result state","diagramHtmlDark":"XMoneyAPIXMoneySDKMerchantBackendCheckoutWebPageMobileAppXMoneyAPIXMoneySDKMerchantBackendCheckoutWebPageMobileAppalt[Requires3DS]Open WebView checkout URLCreate inline checkout orderpublicKey, orderPayload, orderChecksumMount paymentForm or custom widgetsProcess card, wallet, or saved card paymentWebView opens authentication flowonPaymentComplete or onErrorNotify native shell of result state"},"children":["sequenceDiagram\n participant mobileApp as MobileApp\n participant checkoutPage as CheckoutWebPage\n participant merchantBackend as MerchantBackend\n participant xMoneySdk as XMoneySDK\n participant xMoneyApi as XMoneyAPI\n\n mobileApp->>checkoutPage: Open WebView checkout URL\n checkoutPage->>merchantBackend: Create inline checkout order\n merchantBackend-->>checkoutPage: publicKey, orderPayload, orderChecksum\n checkoutPage->>xMoneySdk: Mount paymentForm or custom widgets\n xMoneySdk->>xMoneyApi: Process card, wallet, or saved card payment\n alt Requires3DS\n xMoneySdk-->>mobileApp: WebView opens authentication flow\n end\n xMoneySdk-->>checkoutPage: onPaymentComplete or onError\n checkoutPage-->>mobileApp: Notify native shell of result state\n"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"web-checkout-page","__idx":2},"children":["Web checkout page"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The WebView should load a normal HTTPS checkout page that includes the SDK script and mounts one of the inline checkout widgets."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"html","header":{"controls":{"copy":{}}},"source":"\n
\n","lang":"html"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"const paymentForm = await window.XMoney.paymentForm({\n container: 'xmoney-payment-form',\n publicKey,\n orderPayload,\n orderChecksum,\n paymentMethods: {\n applePay: { enabled: true },\n googlePay: { enabled: true },\n },\n options: {\n locale: 'en-US',\n enableBackgroundRefresh: true,\n },\n onPaymentProcessing(isProcessing) {\n notifyNativeApp({ type: 'payment-processing', isProcessing })\n },\n onPaymentComplete(transaction) {\n notifyNativeApp({ type: 'payment-complete', transaction })\n },\n onError(error) {\n notifyNativeApp({ type: 'payment-error', error })\n },\n})\n\nfunction notifyNativeApp(message) {\n window.webkit?.messageHandlers?.xmoneyCheckout?.postMessage(message)\n window.XMoneyAndroid?.postMessage?.(JSON.stringify(message))\n}\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The native bridge is optional. You can also show result states entirely inside the WebView."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"native-shell-responsibilities","__idx":3},"children":["Native shell responsibilities"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Keep native code focused on WebView lifecycle, not payment business logic."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The native app should:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Open the checkout URL in a secure WebView or browser tab."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Show native loading, cancel, and retry states around the WebView."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Preserve the checkout page when the app is backgrounded."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Allow 3DS and wallet flows to open required external contexts."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Wait for the web checkout result before closing the WebView."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Ask your backend for final order status before showing fulfillment states."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The native app should not collect PAN or duplicate the payment form in native UI."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"ios-guidance","__idx":4},"children":["iOS guidance"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WKWebView"]},":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use HTTPS for the checkout page."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Allow JavaScript and window opening behavior needed by wallet and 3DS flows."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Preserve the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WKWebView"]}," instance during backgrounding when possible."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Handle universal links or callback URLs that may return from a bank authentication app."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Do not clear cookies or website data during an active checkout."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you use Apple Pay, validate the complete flow on real devices. Apple Pay availability depends on the device, browser/WebView capabilities, wallet setup, merchant activation, and domain verification."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"android-guidance","__idx":5},"children":["Android guidance"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For Android WebView:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Enable JavaScript for the checkout page."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WebChromeClient"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WebViewClient"]}," configuration that supports popups or external URL handling required by 3DS."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Persist the checkout URL and any invocation context across activity recreation."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Handle app links or return URLs that may resume the checkout after bank authentication."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Prefer Custom Tabs if your WebView policy blocks wallet or 3DS requirements."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Google Pay availability depends on device support, Google Play services, wallet setup, merchant activation, and browser/WebView support."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"3ds-lifecycle-rules","__idx":6},"children":["3DS lifecycle rules"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["3DS may temporarily move the shopper away from your checkout view. To avoid losing the payment state:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Keep ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["enableBackgroundRefresh: true"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Do not close or recreate the checkout WebView during authentication."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Persist enough state to reopen the same checkout page if the OS kills the app."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Treat ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onPaymentComplete"]}," as a client signal and confirm final status server-side."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/checkout/inline-checkout/3ds-results"},"children":["3DS and payment results"]}," for callback behavior."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"shared-web-and-mobile-code","__idx":7},"children":["Shared web and mobile code"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A practical pattern is to keep one checkout page that works in both a browser and WebView:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"const isNativeWebView =\n Boolean(window.webkit?.messageHandlers?.xmoneyCheckout) ||\n Boolean(window.XMoneyAndroid)\n\nfunction finishCheckout(transaction) {\n if (isNativeWebView) {\n notifyNativeApp({ type: 'payment-complete', transaction })\n return\n }\n\n window.location.href = `/checkout/result?orderId=${transaction.externalOrderId}`\n}\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This keeps payment behavior consistent while still letting the native app control the surrounding experience."]},{"$$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/checkout/inline-checkout/web-integration"},"children":["Website integration"]}]},{"$$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":"Mobile WebView Integration","id":"mobile-webview-integration","depth":1},{"value":"Recommended architecture","id":"recommended-architecture","depth":2},{"value":"Web checkout page","id":"web-checkout-page","depth":2},{"value":"Native shell responsibilities","id":"native-shell-responsibilities","depth":2},{"value":"iOS guidance","id":"ios-guidance","depth":2},{"value":"Android guidance","id":"android-guidance","depth":2},{"value":"3DS lifecycle rules","id":"3ds-lifecycle-rules","depth":2},{"value":"Shared web and mobile code","id":"shared-web-and-mobile-code","depth":2},{"value":"Related guides","id":"related-guides","depth":2}],"frontmatter":{"seo":{"title":"Inline Checkout in Mobile WebViews | xMoney Documentation","description":"Use the xMoney inline checkout SDK inside iOS and Android WebViews while preserving wallet, 3DS, and lifecycle behavior."}},"lastModified":"2026-06-19T09:28:44.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/checkout/inline-checkout/mobile-webview","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}