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.

Configure a custom URL scheme in Xcode.

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:) to confirm the pass exists on the device.

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.

Example deep link:

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

Swift example:

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
}

For more details on custom URL schemes, check the Apple documentation.

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.

This sample code is provided as-is.

Use the latest Apple specifications.

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

The deviceAccountIdentifier maps to digitalCardId in D1 and to virtualCardId on TSH.

Use it to activate the digital card.

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.