Mobile WebView Integration

The embedded checkout renders from a URL, so any mobile app can display it in a WebView: create an order server-side, build the checkout URL, and load it. This guide covers the direct WebView integration for apps that do not use a Crossmint client SDK, including native iOS (Swift) and Android (Kotlin) apps.

The React Native, Flutter, and Kotlin SDKs render and configure this WebView for you. If you build with one of those frameworks, start from the SDK instead and return here only if you need full control over the WebView.

Prerequisites

API keys: From the Crossmint Console, under Integrate → API Keys, create a server key (sk_staging_...) with the orders.create and orders.read scopes, and a client key (ck_staging_...) with the orders.read scope.
A recipient wallet: purchased assets are delivered to a wallet address that you pass at order creation.
A backend: order creation uses the server key, which must never ship inside the app.

Integration

Create the order server-side

Create the order from your backend and return the orderId and clientSecret to the app. The order carries the item, the recipient, and optionally the receipt email, so the checkout never needs to ask the user for them:

// server.js
const CROSSMINT_SERVER_API_KEY = "YOUR_SERVER_API_KEY"; // sk_staging_...

// sk_staging_ keys pair with staging.crossmint.com,
// sk_production_ keys with www.crossmint.com
const BASE_URL = "https://staging.crossmint.com";

async function createOrder(walletAddress) {
    const res = await fetch(`${BASE_URL}/api/2022-06-09/orders`, {
        method: "POST",
        headers: {
            "Content-Type": "application/json",
            "x-api-key": CROSSMINT_SERVER_API_KEY,
        },
        body: JSON.stringify({
            lineItems: {
                // XMEME test token on Solana (staging only)
                tokenLocator: "solana:7EivYFyNfgGj8xbUymR7J4LuxUHLKRzpLaERHLvi7Dgu",
                executionParameters: {
                    mode: "exact-in",
                    amount: "5",
                    maxSlippageBps: "500",
                },
            },
            payment: { method: "card" }, // wallet payment methods ride this rail at creation time
            recipient: { walletAddress },
        }),
    });

    const data = await res.json();
    if (!res.ok) {
        throw new Error(data.message ?? "Order creation failed");
    }
    return {
        orderId: data.order.orderId,
        clientSecret: data.clientSecret,
    };
}

The example uses a token line item; NFT collection line items work the same way. See the create order API reference for all line item types and options.

Build the checkout URL

The checkout page accepts its configuration as URL query parameters:

Parameter	Value
`orderId`	From order creation
`clientSecret`	From order creation
`apiKey`	Your client key (`ck_...`)
`payment`	URL-encoded JSON. Same options as the `payment` prop of the React component
`appearance`	URL-encoded JSON. Same options as the `appearance` prop of the React component

const BASE_URL = "https://staging.crossmint.com"; // www.crossmint.com in production
const CLIENT_API_KEY = "YOUR_CLIENT_API_KEY"; // ck_staging_...

const payment = {
    crypto: { enabled: false },
    fiat: {
        enabled: true,
        allowedMethods: { applePay: true, card: false, googlePay: true },
    },
};

const appearance = {
    rules: {
        DestinationInput: { display: "hidden" },
        ReceiptEmailInput: { display: "hidden" },
        GlobalMessage: { display: "visible" },
    },
};

function buildCheckoutUrl(orderId, clientSecret) {
    const params = new URLSearchParams({
        orderId,
        clientSecret,
        payment: JSON.stringify(payment),
        appearance: JSON.stringify(appearance),
        apiKey: CLIENT_API_KEY,
    });
    return `${BASE_URL}/sdk/2024-03-05/embedded-checkout?${params.toString()}`;
}

Every configuration option from payment methods and UI customization works here. The example above renders a wallet-button-only checkout; see the one-tap Apple Pay quickstart for that experience end to end.

Render the URL in a WebView

A few WebView settings make the difference between a checkout that shows Apple Pay and Google Pay and one that silently does not. The tabs below contain the tested configuration per platform:

React Native
Android (Kotlin)
iOS (Swift)

Requires react-native-webview version 13.15.0 or higher.

import { Platform } from "react-native";
import { WebView } from "react-native-webview";

// A standard mobile browser userAgent. The default WebView userAgent
// identifies as an app, and the checkout hides wallet buttons for it.
const userAgent = Platform.select({
    ios: "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1",
    android:
        "Mozilla/5.0 (Linux; Android 14) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Mobile Safari/537.36",
});

export function CheckoutWebView({ checkoutUrl }: { checkoutUrl: string }) {
    return (
        <WebView
            source={{ uri: checkoutUrl }}
            userAgent={userAgent}
            paymentRequestEnabled={true} // Google Pay; no effect on iOS
            allowsInlineMediaPlayback={true}
            mediaPlaybackRequiresUserAction={false}
            domStorageEnabled={true}
        />
    );
}

For Google Pay, the app also needs the Android payment intent declaration from the Google Pay guide.

Add the androidx.webkit dependency to reach the Payment Request setting, which Google Pay requires and Android WebView ships disabled:

import android.webkit.WebChromeClient
import android.webkit.WebView
import android.webkit.WebViewClient
import androidx.webkit.WebSettingsCompat
import androidx.webkit.WebViewFeature

fun configureCheckoutWebView(webView: WebView, checkoutUrl: String) {
    webView.settings.apply {
        javaScriptEnabled = true
        domStorageEnabled = true
        userAgentString =
            "Mozilla/5.0 (Linux; Android 14) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Mobile Safari/537.36"
    }
    if (WebViewFeature.isFeatureSupported(WebViewFeature.PAYMENT_REQUEST)) {
        WebSettingsCompat.setPaymentRequestEnabled(webView.settings, true)
    }
    // Default clients keep every step of the checkout inside the WebView
    webView.webViewClient = WebViewClient()
    webView.webChromeClient = WebChromeClient()
    webView.loadUrl(checkoutUrl)
}

Declare the payment intent in AndroidManifest.xml so Google Pay can respond:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <queries>
        <intent>
            <action android:name="org.chromium.intent.action.PAY" />
        </intent>
    </queries>
</manifest>

WKWebView needs inline media playback enabled; its other defaults work with the checkout as-is:

import WebKit

func makeCheckoutWebView(checkoutUrl: URL) -> WKWebView {
    let configuration = WKWebViewConfiguration()
    configuration.allowsInlineMediaPlayback = true
    configuration.mediaTypesRequiringUserActionForPlayback = []

    let webView = WKWebView(frame: .zero, configuration: configuration)
    webView.load(URLRequest(url: checkoutUrl))
    return webView
}

If your app declares WKAppBoundDomains in its Info.plist, WebKit restricts every WKWebView to those domains. Add the domains listed under “Restricting navigation” below to that list, or the checkout cannot complete.

Keep navigation inside the WebView unrestricted, and keep iframes enabled. To complete an order, the checkout navigates to pages from Crossmint’s payment method and identity partners, and a WebView that blocks those pages interrupts the purchase with no visible error.

Restricting navigation: the domains the checkout uses

If your security policy requires a navigation allowlist, include these domains, grouped by what they render during checkout:

Purpose	Domains
Checkout and order pages	`crossmint.com`
Card and wallet payment methods	`stripe.com`, `checkout.com`, `pay.google.com`, `applepay.cdn-apple.com`
Identity verification and risk screening	`withpersona.com`, `sardine.ai`

Match subdomains as well (for example *.crossmint.com), and revisit the list when you update the SDK or change payment methods.

Track the order

The checkout page reports progress with messages. In React Native, listen with onMessage:

<WebView
    // ...configuration from the previous step
    onMessage={(event) => {
        const message = JSON.parse(event.nativeEvent.data);
        // message.event is one of:
        //   order:updated              order phase changes; "delivery" means the purchase succeeded
        //   order:creation-failed     the order could not initialize
        //   ui:height.changed          the checkout has rendered content
        //   ui:express-checkout.ready  the wallet button is interactive
        if (message.event === "order:updated" && message.data?.order?.phase === "delivery") {
            // show your success state
        }
    }}
/>

On iOS (Swift) and Android (Kotlin), track the order from your backend instead: subscribe to webhooks or poll the get order endpoint with the orderId you already hold.

Test on a physical device

Wallet payment methods render on real hardware: test Apple Pay on an iPhone running iOS 17 or higher with a card added to Apple Wallet, and Google Pay on an Android device with Google Play Services. In staging, wallet payments run against a test environment, so the card behind the wallet is never charged.To exercise the full purchase from a simulator or emulator during development, enable the card form (allowedMethods: { card: true, ... }) and pay with the staging test card 4242 4242 4242 4242. More options are listed in testing tips.

Troubleshooting

The wallet button does not render

Set a standard mobile browser userAgent on the WebView (step 3). The checkout serves wallet buttons to mobile browsers, and the default WebView userAgent identifies as an app.
For Google Pay, enable the Payment Request setting and declare the payment intent in the manifest (step 3), and test on a device with Google Play Services.
For Apple Pay, use a physical iPhone on iOS 17 or higher: the iOS Simulator does not render Apple Pay.
Confirm the order was created successfully and payment in the URL enables the wallet you expect.

The payment sheet opens but the purchase never completes

A navigation restriction is usually interrupting the checkout mid-purchase. Remove custom WebViewClient/WKNavigationDelegate rules that cancel navigations, or extend your allowlist with the domains listed under “Restricting navigation” above.

The checkout page does not load

Enable JavaScript and DOM storage on the WebView (step 3).
Match the base URL to the key environment: ck_staging_/sk_staging_ keys pair with staging.crossmint.com, production keys with www.crossmint.com.
Confirm the payment and appearance parameters contain valid JSON after URL encoding.

A payment fails and nothing appears on screen

Pass GlobalMessage: { display: "visible" } inside appearance.rules (step 2). In layouts that hide the checkout inputs, this rule is the surface where payment errors render.

FAQ

Can a Crossmint SDK handle this for me?

Yes. The React Native, Flutter, and Kotlin SDKs apply this WebView configuration automatically and expose the checkout as a component. Use this guide when you need your own WebView, or on platforms without an SDK, such as native iOS (Swift).

Do I need to register a domain for Apple Pay?

No. Apple Pay domain registration applies to websites that embed the checkout. In this integration the checkout page is served from crossmint.com, which is already enabled for Apple Pay.

How do I render only the Apple Pay or Google Pay button?

Restrict the payment methods and hide the checkout inputs through the payment and appearance URL parameters. The one-tap Apple Pay quickstart covers the complete configuration, and every setting in it maps directly onto the URL parameters from step 2.

Can I open the checkout in a browser instead of a WebView?

Yes. The checkout URL also renders in SFSafariViewController, Chrome Custom Tabs, or a regular browser tab. A WebView keeps the checkout inside your own screens; a browser surface takes less configuration and suits flows where opening a sheet over the app is acceptable.

Which payment methods can users see?

The same ones as the embedded checkout on web: cards, Apple Pay, Google Pay, and crypto, controlled by the payment URL parameter. See payment methods.

Next Steps

One-Tap Apple Pay

Render only the wallet button and build the rest of the experience in your own UI

Google Pay Mobile

Production approval and native Android configuration for Google Pay

UI Customization

Theme the checkout through the appearance parameter

Introduction

Hosted (pop-up)

Embedded

Headless (API)

Advanced Guides

API Reference

Mobile WebView Integration

Prerequisites

Integration

Troubleshooting

FAQ

Next Steps

One-Tap Apple Pay

Google Pay Mobile

UI Customization

​Prerequisites

​Integration

​Troubleshooting

​FAQ

​Next Steps

One-Tap Apple Pay

Google Pay Mobile

UI Customization

Prerequisites

Integration

Troubleshooting

FAQ

Next Steps