Apple Pay

Scheme TSP configuration

The redirection information is as follows:

• contactName: Identifier of the issuer name (see the diagram above).

• bank_app: Name of the iOS app used for in-app authentication.

• appLaunchURL: Dedicated deep link URL scheme for the issuer application. Apple Pay uses it to launch the issuer application for in-app authentication. The issuer application can then determine it was launched by the wallet application based on the URL scheme value.

• associatedStoreIdentifiers: Identifiers of the issuer application in the App Store. Apple Pay uses them to prompt the end user to download the issuer application if it is not installed.

• associatedApplicationIdentifiers: Identifiers of the issuer application. They must match your developer account Team ID and app bundle ID.

Set up and handle a custom URL scheme

1. In Xcode, go to Project Settings > Targets > your application and select the Info tab of your target.

   • Set identifier to a unique identifier. The recommended value is the application bundle ID.

   • Set URL Schemes to your custom scheme.

   • Set Role to Editor.

1. When the wallet application redirects the end user to the issuer application, the issuer application must verify it was launched by the wallet application. The wallet application appends query parameters to the URL. These parameters uniquely identify the pass (digital card). For example, myscheme://mypath?passTypeIdentifier=paymentpass.com.apple&serialNumber=123&action=verify.

For details, see the Apple documentation.

Card and token identification

To identify the card and token to activate, the issuer application must use the iOS PassKit APIs. In particular, use these parameters:

• passTypeIdentifier

• serialNumber

In iOS terms, these parameters let you identify the Pass. In this flow, the Pass is the token to activate.

Below is sample Swift code that shows how to use this data to identify the Pass.

Warning

This sample code is provided as-is. You are responsible for using the latest Apple specifications. Thales is not responsible for changes Apple may introduce to the PassKit APIs.

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 indexSerialNumber = queryItems.firstIndex(where: { $0.name == "serialNumber" })
    let containsAction = queryItems.contains(where: { $0.name == "action" })
    let validated = containsPassTypeIdentifier && indexSerialNumber != nil && containsAction

    guard validated, let indexSerialNumber = indexSerialNumber else {
        // handle error e.g. show error UI
        return false
    }

    var serialNumber = queryItems[indexSerialNumber].value
    let tokenRequestorId = "40010030273" // only in case of VISA, else empty string
    let scheme = "SCHEME" // VISA, MASTERCARD, AMEX
    let authorizationCode = "<JWT>" // provide JWT value related to particular card, retrieved from issuer backend

    if let serialNumber = serialNumber {
        let tokenInput = GetTokenInput(serialNumber: serialNumber)
        TPCSDK.getToken(input: tokenInput) {
            (localPass, remotePass, error) in
            if let error = error {
                // handle TPC error
                return
            }
            
            var tokenId: String? = nil
            var last4: String? = nil
            if let localPass = localPass {
                last4 = localPass.secureElementPass?.primaryAccountNumberSuffix
                tokenId = localPass.secureElementPass?.deviceAccountIdentifier
            } else if let remotePass = remotePass {
                last4 = remotePass.secureElementPass?.primaryAccountNumberSuffix
                tokenId = remotePass.secureElementPass?.deviceAccountIdentifier
            }

            if let last4 = last4,
                let tokenId = tokenId {

                // show last4 for confirmation UI

                TPCSDK.updateTokenState(tokenId: tokenId,
                                        tokenRequestorId: tokenRequestorId,
                                        schemeString: scheme,
                                        authorizationCode: authorizationCode,
                                        action: .Activate) { success, error in
                    if let error = error {
                        // handle TPC Error
                    } else if success {
                        // todo: refresh UI to indicate state of the card digitization
                    }
                }
            }
        }
    } else {
        // handle error e.g. show error UI
        return false
    }
    return true
}

Note:

The deviceAccountIdentifier corresponds to the token ID in TSP. You can use it to activate the token for the digitized card. The primaryAccountNumberSuffix is the last four digits of the PAN that has been tokenized. You can use it to retrieve the card art and show it to the end user during the authentication request.