Add Payment Methods

This guide covers how to enable each supported payment method — cards, Apple Pay, and Google Pay — in your onramp integration, including the platform-specific configuration each one requires. All payment methods are controlled through the payment configuration of the checkout component. The checkout only displays methods that the user’s device supports, so enabling a method is safe even on platforms where it cannot appear. For an explanation of how each method works, see Payment Methods.

Prerequisites

A working onramp integration — complete a quickstart first.

Configure Allowed Methods

Set the methods you want to offer in the fiat payment configuration:

React
React Native
Flutter
Kotlin
Swift

<CrossmintEmbeddedCheckout
    orderId={order.orderId}
    clientSecret={order.clientSecret}
    payment={{
        crypto: { enabled: false },
        fiat: {
            enabled: true,
            allowedMethods: {
                card: true,
                applePay: true,
                googlePay: true,
            },
        },
    }}
/>

<CrossmintEmbeddedCheckout
    orderId={order.orderId}
    clientSecret={order.clientSecret}
    payment={{
        crypto: { enabled: false },
        fiat: {
            enabled: true,
            allowedMethods: {
                card: true,
                applePay: true,
                googlePay: true,
            },
        },
    }}
/>

CrossmintEmbeddedCheckout(
  apiKey: clientApiKey,
  config: CrossmintCheckoutConfig(
    order: CrossmintCheckoutExistingOrder(
      orderId: order.orderId,
      clientSecret: order.clientSecret,
    ),
    payment: CrossmintCheckoutPayment(
      crypto: CrossmintCheckoutCryptoPayment(enabled: false),
      fiat: CrossmintCheckoutFiatPayment(
        enabled: true,
        allowCard: true,
        allowApplePay: true,
        allowGooglePay: true,
      ),
    ),
  ),
)

CrossmintEmbeddedCheckout(
    orderId = "YOUR_ORDER_ID",
    clientSecret = "YOUR_CLIENT_SECRET",
    payment = CheckoutPayment(
        crypto = CheckoutCryptoPayment(enabled = false),
        fiat = CheckoutFiatPayment(
            enabled = true,
            allowedMethods = CheckoutAllowedMethods(
                card = true,
                applePay = true,
                googlePay = true
            )
        )
    ),
    environment = CheckoutEnvironment.STAGING
)

CrossmintEmbeddedCheckout(
    orderId: "YOUR_ORDER_ID",
    clientSecret: "YOUR_CLIENT_SECRET",
    payment: CheckoutPayment(
        crypto: CheckoutCryptoPayment(enabled: false),
        fiat: CheckoutFiatPayment(
            enabled: true,
            allowedMethods: CheckoutAllowedMethods(
                googlePay: false,
                applePay: true,
                card: true
            )
        )
    )
)

Cards work on every platform with no additional setup. Apple Pay and Google Pay require the platform-specific configuration below.

Apple Pay

Web (React)
iOS (Swift)

To display Apple Pay on your website (Safari on macOS and iOS), you must verify your domain with Apple through the Crossmint Console. This is a one-time setup per domain.

Prerequisites

HTTPS hosting — your site must be served over HTTPS.
Crossmint account — you need an active Crossmint developer account.

Download the Verification File

Go to the Apple Pay Domains page in the Crossmint Console and click Download file to get the Apple Developer Merchant ID Domain Association file.

Host the Verification File

Host the downloaded file on your server at the following path:

https://YOUR_DOMAIN/.well-known/apple-developer-merchantid-domain-association

Example: Next.js App Router

Option 1: Using the Public Folder

Create the .well-known folder inside your public directory.
Place the downloaded file in public/.well-known/ with the filename apple-developer-merchantid-domain-association (no extension).

Option 2: Using a Route

Create a folder at app/.well-known/apple-developer-merchantid-domain-association/
Add a route.ts file with the following content:

route.ts

import { NextResponse } from "next/server";

export async function GET() {
    return new NextResponse("PASTE_FILE_CONTENT_HERE", {
        headers: {
            "Content-Type": "text/plain",
        },
    });
}

Replace PASTE_FILE_CONTENT_HERE with the content of the downloaded verification file.

Example: Next.js Page Router

Create the .well-known folder inside your public directory.
Place the downloaded file in public/.well-known/ with the filename apple-developer-merchantid-domain-association (no extension).

Example: Vite

Create the .well-known folder inside your public directory.
Place the downloaded file in public/.well-known/ with the filename apple-developer-merchantid-domain-association (no extension).

Verify Your Domain

Return to the Apple Pay Domains page in the Crossmint Console.
Enter your domain (e.g., example.com or checkout.example.com) in the input field.
Click Verify domain.

If verification succeeds, your domain will appear in the list of registered domains and Apple Pay will be available as a payment method in the onramp checkout.

If verification fails, ensure the file is publicly accessible at the correct path. You can test by visiting https://YOUR_DOMAIN/.well-known/apple-developer-merchantid-domain-association in your browser.

Local Testing

Using ngrok is recommended for local testing:

Start ngrok with a fixed domain if possible for consistent testing.
Host the verification file on your local server.
Register the ngrok domain in the Crossmint Console.
Test Apple Pay on Safari (macOS) or any iOS device.

Apple Pay is supported automatically in native iOS apps via the Swift SDK — no domain verification is required. Enable it through allowedMethods as shown in Configure Allowed Methods, and see the Swift Quickstart for the full integration.

Google Pay

On the web, Google Pay works out of the box — enabling it via allowedMethods is all that is needed. Mobile apps require additional native configuration because the payment sheet is rendered by the operating system.

React Native
Android Native (Kotlin)

Prerequisites

React Native project with Expo or bare workflow
Android device or emulator with Google Play Services

Install Dependencies

pnpm add @crossmint/client-sdk-react-native-ui

The SDK includes react-native-webview as a dependency. If you need to install it separately, ensure version 13.15.0 or higher:

pnpm add react-native-webview@^13.15.0

Configure the Expo Plugin

Update your app.json to enable Google Pay:

{
  "expo": {
    "plugins": [
      [
        "@crossmint/client-sdk-react-native-ui",
        {
          "enableGooglePay": true
        }
      ]
    ]
  }
}

This plugin modifies native Android permissions required for Google Pay. The app must be rebuilt after adding this configuration.

Rebuild Your App

Hot reload cannot apply the permission changes. You must rebuild:

npx expo run:android

Or for bare React Native:

npx react-native run-android

Enable Google Pay in the Checkout Component

Set googlePay: true in allowedMethods as shown in Configure Allowed Methods.

Prerequisites

Minimum Android SDK version 24 (Android 7.0)
Jetpack Compose

Add the SDK Dependency

In your app-level build.gradle.kts:

dependencies {
    implementation("com.crossmint:crossmint-sdk-android:0.0.9")
}

Configure AndroidManifest.xml

Add the required query intents to enable Google Pay functionality:

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

Enable Google Pay in the Checkout Component

Set googlePay = true in allowedMethods as shown in Configure Allowed Methods.

Google Pay Production Approval

Google Pay works immediately in staging environments. For production, Google requires explicit approval of your Android app.

Step 1: Create Your Business Profile

Navigate to the Google Pay & Wallet Console
Select “Merchant” as your business type
Complete all business profile information
Navigate to Google Pay API and click “Get Started”
Accept the Google Pay API Terms of Service
Note your Merchant ID (top-right corner after completion)

Step 2: Submit Your Android App for Approval

In the Google Pay & Wallet Console:

Navigate to Google Pay API then Integrations then Integrate with your Android app
Locate your Android application and click “Manage”
Select your integration type (typically “Gateway”)
Upload screenshots of your TEST Google Pay integration
Click “Save” then “Submit for approval”

Required Screenshots:

Product/item selection showing Google Pay option
Cart or checkout view with payment options
Google Pay payment sheet with card selection
Confirmation or receipt screen

Step 3: Go Live

After Google approval (typically ~1 business day):

Sign your APK with a release key (debug keys do not work in production)
Update environment settings:
- Kotlin: environment = CheckoutEnvironment.PRODUCTION
- React Native: Use production API key
Publish your app to Google Play Store

Troubleshooting

Apple Pay button does not appear

Domain not verified (web): Verify your domain on the Apple Pay Domains page
Unsupported browser: Apple Pay on web only appears in Safari on macOS and iOS
Payment method disabled: Check applePay: true in allowedMethods

Google Pay button does not appear

Plugin not configured: Verify enableGooglePay: true in app.json plugins
App not rebuilt: Run npx expo run:android after adding the plugin
Environment mismatch: Staging works without approval; production requires it
Payment method disabled: Check googlePay: true in allowedMethods

PaymentRequest API is not supported error

AndroidManifest missing queries: Add all three Chromium intent queries
Native rebuild required: Hot reload cannot apply permission changes
Device requirements: User needs Google Play Services 25.18.30+ and WebView 137+

Prerequisites

Configure Allowed Methods

Apple Pay

Prerequisites

Local Testing

Google Pay

Prerequisites

Prerequisites

Google Pay Production Approval

Troubleshooting

Next Steps

Payment Methods

UI Customization

User Onboarding

React Quickstart

​Prerequisites

​Configure Allowed Methods

​Apple Pay

​Prerequisites

​Local Testing

​Google Pay

​Prerequisites

​Prerequisites

​Google Pay Production Approval

​Troubleshooting

​Next Steps

Payment Methods

UI Customization

User Onboarding

React Quickstart

Prerequisites

Configure Allowed Methods

Apple Pay

Prerequisites

Local Testing

Google Pay

Prerequisites

Prerequisites

Google Pay Production Approval

Troubleshooting

Next Steps