Onboard Payment Passkeys

Before you begin

• Configure deep links in your issuer application for the callback URL (Android/iOS)
• Use HTTPS links whenever possible. They provide stronger security than custom schemes.
• For Mastercard on iOS versions earlier than 17.4, use a custom scheme.

  • Mastercard only support ASWebAuthenticationSession with shared cookie, if https is used in issuer callback and device is below 17.4, SDK would return error.

Android

1. Configure a callback:

• A custom-scheme callback, such as myapp://, needs no additional configuration.
• A Universal Link callback, such as https://, requires an associated domain and an assetlinks.json file.

  • Host assetlinks.json at:

    https://<your-domain>/.well-known/assetlinks.json

assetlinks.json

 [
  {
    "relation": [
      "delegate_permission/common.handle_all_urls",
      "delegate_permission/common.get_login_creds"
    ],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.mybank",
      "sha256_cert_fingerprints": [
        "A4:D8:8F:E6:22:B2:43:C2:70:80:63:9A:28:0D:73:18:F5:0F:24:84:BE:D0:7D:71:28:24:1C:7C:8A:06:2D:C9"
      ]
    }
  }
]

1. Add App Link and custom-scheme intent filters to your Android manifest:

• Do not change the activity state during a Payment Passkey API operation. For example, do not rotate the device. Do not start another Payment Passkey API operation until the current operation completes.
• Register an activity to receive the intent from the Chrome Custom Tab. Set its launchMode to singleTask.

AndroidManifest.xml

<activity
    android:name=".MainActivity"
    android:exported="true"
    android:launchMode="singleTask">

    <!-- App Link filter -->
    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data
            android:scheme="https"
            android:host="<your-domain>" />
    </intent-filter>

    <!-- Custom-scheme filter -->
    <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="myapp"
            android:host="passkey" />
    </intent-filter>
</activity>

iOS

1. Configure a callback:

• A custom-scheme callback, such as myapp://, needs no additional configuration.
• A Universal Link callback, such as https://, requires an associated domain and an apple-app-site-association file.

  • Host apple-app-site-association at:

    https://<your-domain>/.well-known/apple-app-site-association

  apple-app-site-association

  {
      "webcredentials": {
          "apps": ["<<TEAMID>>.<<app_bundleIdentifier>>"]
      }
  }

1. Configure the associated domain

In Xcode, add the associated domain to your app target's Signing & Capabilities settings.

Use the following entitlement:

App.entitlements

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>com.apple.developer.associated-domains</key>
    <array>
        <string>webcredentials:<your-domain></string>
    </array>
</dict>
</plist>