Overview

The checkout service provides a Hosted Payment Page with full Apple Pay and Google Pay support already built in. This guide covers integration for native iOS/Android apps and React Native apps.

Key Integration Approach

Mobile apps integrate by loading the checkout URL in a properly configured WebView. The checkout page then invokes native Apple Pay / Google Pay sheets directly via the browser's standard W3C Payment Request API.

Important: The mobile app does NOT need to integrate any native payment SDK (PassKit, Google Play Services Wallet), configure Merchant IDs, or request payment entitlements.

Platform Support Requirements

Platform	Requirements
Native iOS	iOS 13.0+ (`WKWebView` natively supports W3C Payment Request API)
Native Android	Android API 26+ (Android 8.0+), Google Play Services 25.18.30+, Chrome WebView 137+
React Native	`react-native-webview` v11.6.0+ (required for `enableApplePay` support on iOS)

Note: Users must have at least one eligible debit card added to their device wallet.

Integration Flow

High-Level Flow

Initiate Top-Up: Your app calls your backend to start a top-up transaction
Receive Checkout URL: Your backend returns a checkout_url (and optionally redirect_url and cancel_url)
Open WebView: Load the checkout_url in a properly configured WebView
Complete Payment: User completes payment through Apple Pay / Google Pay
Handle Completion: Detect completion via callback URL navigation or manual close

What Your App Receives from Backend

Field	Required?	Purpose
`checkout_url`	Required	Load this URL in a WebView to complete payment
`redirect_url`	Optional	Watch for navigation to auto-close WebView upon checkout completion
`cancel_url`	Optional	Watch for navigation to auto-close WebView upon cancellation

Important: Your app only interacts with your own backend — it never calls the payment service provider directly.

Implementation Requirements

iOS Configuration

Native iOS (Swift/Objective-C)

WebView Setup:

Use WKWebView with default configuration
Do NOT inject any JavaScript, WKUserScript, or message handlers (script injection disables Apple Pay in WebKit)
Implement WKNavigationDelegate to monitor navigation for completion detection

Key Requirements:

Load checkout_url in a default-configured WKWebView
Provide a native close button
Test Apple Pay on a real iPhone with Wallet configured (not simulator)

React Native iOS

Required WebView Props:

Prop	Value	Purpose
`enableApplePay`	`true`	Required for Apple Pay availability inside WebView on iOS
`javaScriptEnabled`	`true`	Checkout page requires JavaScript
`domStorageEnabled`	`true`	Required for normal checkout page behavior
`sharedCookiesEnabled`	`true`	Preserves cookie behavior across payment redirects

Critical: Without enableApplePay={true}, Apple Pay can be silently hidden inside the WebView even though the same checkout page works in Safari.

Android Configuration

Native Android (Kotlin/Java)

Required Dependencies:

androidx.webkit:webkit:1.14.0+

AndroidManifest.xml (Android 11+ / API 30+): Add <queries> to allow Chromium WebView to interact with Google Pay services:

<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>

WebView Configuration:

Enable W3C Payment Request API: WebSettingsCompat.setPaymentRequestEnabled(settings, true)
Append User-Agent flag: Add GOOGLE_PAY_SUPPORTED to User-Agent string
Enable third-party cookies: CookieManager.setAcceptThirdPartyCookies(webView, true)
Enable JavaScript and DOM storage

React Native Android

React Native apps on Android require the same native Android configuration as native Android:

<queries> in AndroidManifest.xml
androidx.webkit dependency
Payment Request API enabled
User-Agent flag
Third-party cookies enabled

Note: If react-native-webview does not expose the Payment Request API setting, you may need native Android customization.

WebView Lifecycle Management

Closing the WebView

You have two options for closing the WebView:

Option 1: Manual Close (Simplest)

Do not watch any callback URLs
Provide a top-left close button
Let the user close the WebView when payment is done or abandoned
After closing, poll the order status and refresh balance

Pros: Simplest implementation, no URL monitoring needed

Option 2: Auto-Close (Enhanced UX)

Monitor WebView navigation for redirect_url / cancel_url
Automatically dismiss the WebView when these URLs are detected
Requires your backend to issue redirect_url and cancel_url

Navigation Handling Rules:

Navigation Target	Meaning	Action
`redirect_url` (host + path prefix match)	Checkout finished	Close WebView → query order status → refresh balance
`cancel_url` (host + path prefix match)	User cancelled	Close WebView → return to entry screen
Any other cross-domain hop	3DS / risk / gateway relay	Always allow — not a completion signal

URL Matching Rule

Use same host + path prefix match, not full-string equality. The redirect_url callback typically carries extra query parameters (e.g., ?transactionId=...).

Do NOT use host changes to detect completion. The payment flow passes through several third-party domains (3DS ACS, anti-fraud challenge pages, payment gateway). Only a precise match against redirect_url / cancel_url is a reliable signal.

Order Status Polling

Important: Callback URLs are navigation signals only, not the source of truth. redirect_url is triggered when checkout finishes, whether the payment succeeded, failed, or is still pending.

After the WebView closes, query the order status:

COMPLETED → Payment succeeded; refresh wallet balance
FAILED → Show failure and allow retry
NEW / DEBITED → Still processing; keep polling with backoff

Platform-Specific Notes

iOS Notes

Do	Do Not
Use default `WKWebViewConfiguration` (native) or `enableApplePay={true}` (React Native)	Use deprecated `UIWebView`
Test Apple Pay on a real iPhone with Wallet configured	Expect Apple Pay to work in iOS Simulator
Use navigation callbacks only for close detection	Inject custom JavaScript into the checkout WebView
Allow all intermediate redirects unless they match `redirect_url` or `cancel_url`	Close the WebView just because the domain changes

Android Notes

Requirement	Configuration
AndroidManifest.xml	Add `<queries>` for Chromium payment intents on Android 11+
androidx.webkit	Use `androidx.webkit:webkit:1.14.0+`
Payment Request API	Enable via `WebSettingsCompat.setPaymentRequestEnabled(settings, true)`
User-Agent	Append `GOOGLE_PAY_SUPPORTED` so checkout page can detect Google Pay support
Cookies	Enable third-party cookies for payment gateway, 3DS, and risk redirects

Why No Apple Pay / Google Pay SDK Is Needed

The checkout page leverages the standard W3C Payment Request API:

✅ What the app needs:

A properly configured WebView capable of loading HTTPS pages

❌ What the app does NOT need:

Native payment SDK (PassKit, Google Play Services Wallet)
Its own Merchant ID
Payment certificates, CSR, or token decryption
In-App Payment entitlements

Merchant validation and payment token processing are handled server-side by the payment service provider.

Troubleshooting

Symptom	Likely Cause	Solution
Apple Pay option not shown (native iOS)	WebView had script injected / non-HTTPS / no eligible debit card in wallet	Remove all script injection; ensure URL is HTTPS; add eligible debit card in Apple Wallet
Apple Pay option not shown (React Native)	`enableApplePay` prop missing or iOS Simulator used	Set `enableApplePay={true}`; test on real device with eligible debit card
Google Pay option not shown on Android	Payment Request API not enabled / missing `<queries>` / User-Agent flag missing / cookies disabled	Enable Payment Request API; add `<queries>` to manifest; append `GOOGLE_PAY_SUPPORTED` to User-Agent; enable third-party cookies
WebView does not auto-close after payment	Option 2 not used / `redirect_url` not issued / matched with full string equality	If using auto-close, confirm backend issued `redirect_url` and use host + path prefix matching
WebView closes prematurely mid-flow	A third-party hop (3DS/ACS) was mistaken for completion	Only match against `redirect_url` / `cancel_url`; allow all other cross-domain navigations
User sees success but balance is not updated	App treats `redirect_url` navigation as payment success	Poll order status after WebView close; refresh balance only when order is `COMPLETED`
Error after payment sheet appears	Merchant validation failed	Server-side configuration issue; contact support
Token expired	JWT is short-lived; user lingered too long	Re-run the flow to obtain a fresh checkout URL

Integration Checklist

iOS (Native + React Native)

Load checkout_url in a default-configured WKWebView (native) or WebView with enableApplePay={true} (React Native)
Provide a native close button
Apple Pay is tested on a real iPhone, not the simulator
Test device Wallet has an eligible debit card
(Optional, auto-close) Intercept redirect_url / cancel_url with host + path prefix match and allow all intermediate hops

Android (Native + React Native)

Add androidx.webkit:webkit:1.14.0+ dependency and <queries> block in AndroidManifest.xml
Enable Payment Request API
Set User-Agent with GOOGLE_PAY_SUPPORTED
Enable third-party cookies
Google Pay is tested on a real Android device with an eligible card
(Optional, auto-close) Intercept redirect_url / cancel_url with host + path prefix match

Support Information

When reporting an integration issue, provide:

Platform: iOS or Android
OS version and device model
App framework: Native (Swift/Kotlin) or React Native
If React Native: RN version, react-native-webview version, whether enableApplePay={true} is set
If Android: WebView / Chrome version, whether <queries>, Payment Request API, User-Agent flag, and third-party cookies are configured
Environment: staging or production
Screenshot, screen recording, or WebView logs

Contact the integration support team for hosted checkout or merchant-validation related issues.

How to Integrate Apple Pay / Google Pay in Mobile App