> 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/push-provisioning/integrate-in-app-id-and-v-for-xpay-wallets/apple-pay-in-app-id-and-v.md).

# Apple Pay in-app ID\&V

Use this guidance to support in-app ID\&V when an End User provisions a card to Apple Pay.

You configure redirect parameters in your payment network TSP. Apple Pay uses them to open the issuer application.

### Configure your payment network TSP

Configure these redirect parameters in your payment network TSP:

* **contactName**: Issuer display name shown to the End User.
* **bank\_app**: Issuer application name used for in-app ID\&V.
* **appLaunchURL**: Custom URL scheme that opens the issuer application.
* **associatedStoreIdentifiers**: App Store identifier(s). Used when the issuer application is not installed.
* **associatedApplicationIdentifiers**: Application identifier(s). Typically the Apple Team ID and app bundle ID.

### Implement the issuer application handler

#### Configure a custom URL scheme in Xcode

In Xcode, go to **Project settings** > **Targets** > your app.

Open the `Info` tab.

* Set `identifier` to a unique identifier. Use the app bundle ID.
* Set `URL Schemes` to your custom scheme.
* Set `Role` to `Editor`.

<figure><img src="/spaces/62lLFDcmLCeqqwmy4Fee/files/gQyveN7nt1Gp0yFHb0tz" alt="Xcode Info tab showing URL Types configuration for a custom URL scheme."><figcaption><p>Configure a custom URL scheme in Xcode.</p></figcaption></figure>

#### Handle the deep link and validate the caller

When the digital wallet application redirects the End User to the issuer application, the issuer application must validate the request before starting ID\&V.

Apple Pay appends query parameters that identify the pass. Use them with [`PKPassLibrary.pass(withPassTypeIdentifier:serialNumber:)`](https://developer.apple.com/documentation/passkit/pkpasslibrary/1617104-pass) to confirm the pass exists on the device.

{% hint style="warning" %}
Validate the deep link before you authenticate the End User or activate the digital card.

Treat missing or unexpected parameters as a failed ID\&V attempt.
{% endhint %}

Example deep link:

`myscheme://mypath?passTypeIdentifier=paymentpass.com.apple&serialNumber=123&action=verify`

Swift example:

{% code overflow="wrap" %}

```swift
func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
    guard let components = URLComponents(url: url, resolvingAgainstBaseURL: true) else {
        // handle error e.g. logging
        return false
    }
    
    guard let queryItems = components.queryItems else {
        // handle error e.g. logging
        return false
    }

    // example of checking the query items
    let containsPassTypeIdentifier = queryItems.contains(where: { $0.name == "passTypeIdentifier" && $0.value == "paymentpass.com.apple" })
    let containsSerialNumber = queryItems.contains(where: { $0.name == "serialNumber" })
    let containsAction = queryItems.contains(where: { $0.name == "action" })
    let validated = containsPassTypeIdentifier && containsSerialNumber && containsAction

    if validated {
        // continue with activation
    } else {
        // handle error e.g. show error UI
    }
    
    return validated
}
```

{% endcode %}

For more details on custom URL schemes, check the [Apple documentation](https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app).

### Identify the digital card

Use these parameters from the iOS PassKit API to identify the digital card to activate:

* passTypeIdentifier
* serialNumber

These parameters identify the `Pass` to activate.

The following sample code in Swift describes how to use this data to identify the `Pass`.

{% hint style="warning" %}
This sample code is provided as-is.

Use the latest Apple specifications.
{% endhint %}

{% code overflow="wrap" %}

```swift
func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
    guard let components = URLComponents(url: url, resolvingAgainstBaseURL: true) else {
        // handle error e.g. logging
        return false
    }
    
    guard let queryItems = components.queryItems else {
        // handle error e.g. logging
        return false
    }

    var passTypeIdentifier: String? = nil
    var serialNumber: String? = nil
    var action: String? = nil

    for queryItem in queryItems {
        if queryItem.name == "passTypeIdentifier" {
            passTypeIdentifier = queryItem.value
        } else if queryItem.name == "serialNumber" {
            serialNumber = queryItem.value
        } else if queryItem.name == "action" {
            action = queryItem.value
        }
    }

    if let passTypeIdentifier = passTypeIdentifier,
        let serialNumber = serialNumber,
        action != nil {
        let library = PKPassLibrary()
        if let pendingPass = library.pass(withPassTypeIdentifier: passTypeIdentifier, serialNumber: serialNumber) {
            if #available(iOS 13.4, *) {
                if let primaryAccountNumberSuffix = pendingPass.secureElementPass?.primaryAccountNumberSuffix,
                    let deviceAccountIdentifier = pendingPass.secureElementPass?.deviceAccountIdentifier {
                    // continue with activation through SDK
                }
            } else {
                if let primaryAccountNumberSuffix = pendingPass.paymentPass?.primaryAccountNumberSuffix,
                    let deviceAccountIdentifier = pendingPass.paymentPass?.deviceAccountIdentifier {
                    // continue with activation through SDK
                }
            }
        }
        return true
    } else {
        // handle error e.g. show error UI
        return false
    }
}
```

{% endcode %}

{% hint style="info" %}
The `deviceAccountIdentifier` maps to `digitalCardId` in D1 and to `virtualCardId` on TSH.

Use it to activate the digital card.
{% endhint %}

{% hint style="info" %}
The `primaryAccountNumberSuffix` is the last four digits of the PAN that was tokenized.

Use it to retrieve and display the right card art to the End User during ID\&V.
{% endhint %}


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.payments.thalescloud.io/push-provisioning/integrate-in-app-id-and-v-for-xpay-wallets/apple-pay-in-app-id-and-v.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.