Skip to content
Get started
/
Hosted Pages (HP)
/
/
Integrate with Token.io's...
Last updated

Integrate with Token.io's WebView SDK (Mobile Native)

Token.io's WebView SDK allows you to embed Pay by Bank payment flows securely within your native iOS or Android app. Partners with an existing mobile payment flow can quickly add native-feeling, in-app bank payments powered by Hosted Pages v2.

Follow this guide to integrate the WebView SDK and deliver a seamless, secure Pay by Bank experience for your mobile users.

To use the mobile WebView SDK, you must create a payment session/payment request from your backend. This generates the hosted payment URL for the SDK to launch.

1. Installation

iOS

Copy these files from our iOS WebView SDK repository into your Xcode project:

  • PaymentService.swift
  • PaymentWebView.swift
  • PaymentCompletionHandler.swift
  • Configuration.swift

Android

Copy these files from our Android WebView SDK repository into your Android module:

  • PaymentWebViewActivity.kt
  • UnifiedWebViewClient.kt
  • res/layout/activity_payment_webview.xml

2. Environment Configuration

iOS

Add your custom URL scheme and API keys in Info.plist:

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLName</key>
        <string>com.yourcompany.yourapp.payment</string>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>yourapp</string>
        </array>
    </dict>
</array>
<key>API_KEY_SANDBOX</key>
<string>YOUR_SANDBOX_API_KEY</string>
<key>API_KEY_BETA</key>
<string>YOUR_BETA_API_KEY</string>

Android

Declare your WebView activity and deep link callback in AndroidManifest.xml:

<activity
    android:name=".PaymentWebViewActivity"
    android:exported="false"
    android:screenOrientation="portrait" />
<activity android:name=".YourPaymentActivity">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="yourapp" android:host="payment-complete" />
    </intent-filter>
</activity>

Make sure the API key and environment (sandbox, beta, production) are matched correctly in your settings and backend.

3. Start a Payment Session

Create a payment session or payment request using Token.io's API from your backend. The API will return a hosted payment URL.

  • iOS: Pass the payment URL to PaymentWebView.
  • Android: Pass the payment URL as the "PAYMENT_URL" extra to PaymentWebViewActivity.

Best practice: Always perform authentication and payment creation on your backend to protect credentials.

4. Launch the Secure WebView

iOS (SwiftUI):

// Initiate payment and launch WebView
paymentUrl = tokenPaymentUrl
PaymentWebView(environment: .sandbox, initialUrl: paymentUrl)

Android (Kotlin):

private fun launchTokenWebView(tokenPaymentUrl: String) {
    val intent = Intent(this, PaymentWebViewActivity::class.java).apply {
        putExtra("PAYMENT_URL", tokenPaymentUrl)
        putExtra("CALLBACK_SCHEME", "yourapp")
    }
    tokenWebViewLauncher.launch(intent)
}

5. Handle Payment Results

Results are returned to your app as one of:

  • success
  • failure
  • pending
  • Or error/cancel on abandonment

iOS: Delivered to PaymentCompletionHandler (in-app or via deep link). Android: Delivered via ActivityResult or deep link intent.

  • Use the payment ID returned to look up final payment status via the API or webhook.
  • Always verify payments server-side before providing goods/services.

For details on callback parameters, see Callbacks for Hosted Pages.

6. Example: Payment Session Payloads

GBP (UK Faster Payments):

PaymentService.shared.initiatePayment(
    environment: .sandbox,
    currency: "GBP",
    amountValue: "100.50", // Decimal format, English locale
    localInstrument: "FASTER_PAYMENTS",
    creditorName: "Your Business",
    creditorSortCode: "123456",
    creditorAccountNumber: "12345678"
)

EUR (SEPA):

PaymentService.shared.initiatePayment(
    environment: .sandbox,
    currency: "EUR",
    amountValue: "100.50",
    localInstrument: "SEPA_INSTANT",
    creditorName: "Your Business",
    creditorIBAN: "DE89370400440532013000"
)

Android Example (Kotlin):

val paymentRequest = PaymentRequest(
    initiation = Initiation(
        refId = UUID.randomUUID().toString(),
        flowType = "FULL_HOSTED_PAGES",
        amount = Amount(value = "100.50", currency = "GBP"),
        localInstrument = "FASTER_PAYMENTS",
        creditor = Creditor(
            name = "Your Business",
            sortCode = "123456",
            accountNumber = "12345678"
        ),
        callbackUrl = "yourapp://payment-complete",
        callbackState = UUID.randomUUID().toString()
    ),
    pispConsentAccepted = true
)

7. Clean Up After Payment

Ensure your WebView components are properly disposed after each flow or in case of error.

iOS:
No special action needed; dismiss or remove the WebView.

Android:
Finish the PaymentWebViewActivity and handle cleanup in your payment flow handler as appropriate.

The WebView SDK is designed for mobile native apps only. On mobile browsers, users are redirected out of the app for payment approval. Only use the WebView SDK within a native app context.

If you have any feedback about the developer documentation, please contact devdocs@token.io

Previous page
Next page