> For the complete documentation index, see [llms.txt](https://docs.payments.thalescloud.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.payments.thalescloud.io/payment-passkeys-issuers/integrate-d1-sdk/get-started/2.-onboarding/onboard-payment-passkeys.md).

# Onboard Payment Passkeys

### Before you begin

* Configure deep links in your issuer application for the callback URL ([Android](https://developer.android.com/training/app-links/deep-linking)/[iOS](https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app))
* 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`

{% code title="assetlinks.json" %}

```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"
      ]
    }
  }
]
```

{% endcode %}

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

{% hint style="warning" %}

* 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`.
  {% endhint %}

{% code title="AndroidManifest.xml" %}

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

{% endcode %}

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

  <pre class="language-json" data-title="apple-app-site-association"><code class="lang-json">{
      "webcredentials": {
          "apps": ["&#x3C;&#x3C;TEAMID>>.&#x3C;&#x3C;app_bundleIdentifier>>"]
      }
  }
  </code></pre>

2. Configure the associated domain

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

Use the following entitlement:

{% code title="App.entitlements" %}

```xml
<?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>
```

{% endcode %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.payments.thalescloud.io/payment-passkeys-issuers/integrate-d1-sdk/get-started/2.-onboarding/onboard-payment-passkeys.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.