3. Initialization

NFC Wallet SDK initialization

Note

NFC Wallet SDK does not support iCloud and device backup restore feature.

The digital wallet application (wallet) must initialize the SDK before the NFC Wallet SDK features can be used.

You can use TSHPay.configure API to initialise the SDK. The wallet is required to provide two parameters:

• Cardholder verfication method (CVM)
• Configuration PLIST file

The initialisation of the SDK must be performed each time the application is launched.

Cardholder verification method

The wallet is required to provide the authentication method during SDK initialisation. One of the following authentication methods is selected:

• .userPresence : An authentication method using biometrics (TouchID/FaceID) with fallback to device passcode, or to use device passcode in cases where the biometrics are removed after the card digitization process. MPA can change the authentication method to biometrics or device passcode during the payment verification step.
• biometricOnly :An authentication method using TouchID/FaceID only.

For more details about the cardholder verification method, refer to the API documentation.

Configure PLIST file

A PLIST file has to be created and stored in the main bundle of the mobile application.

TSHPay.plist

TSHPay.plist parameters description

KEY	COMMENT
REALM	[String] A fixed parameter. For example, "CBP".
OAUTH_CONSUMER_KEY	[String] Consumer Key which is to be provided by Thales.
GATEWAY_URL	[String] The URL of the Rages which is to be provided by Thales.
CSR_DOMAIN	[String] Used for Certificate Signing Request in the component that secures the HTTPS calls. Refer to your Thales integrator for the value to be set.
CSR_EMAIL	[String] Company email.
CPS_URL	[String] The URL of the CPS server which is to be provided by your Thales integrator.
MG_CONNECTION_URL	[String] The URL of the MG server which is to be provided by Thales.
MG_WALLET_PROVIDER_ID	[String] The ID of the wallet provider.
MG_WALLET_APPLICATION_ID	[String] The ID of the wallet provider's application which is an optional input from the customer. This is required when the wallet provider supports several wallet applications.
TRANSACTION_HISTORY_CONNECTION_URL	[String] The URL for retrieving transaction history which is to be provided by Thales.
SECURE_LOG_LEVEL	[Number] Defines the level of logs to be written where off = 0, fatal = 1, error = 2, warn = 3, info = 4, and debug = 5.
DOMESTIC_CURRENCY_CODE	[Number] The domestic currency code configuration is provided according to ISO-4217 Standard numeric format. Please omit leading '0's in the currency code number. If not configured, default value is 978(Euro).
VISA_ONLINEPIN_PRIORITY	[Boolean] Configure Visa Online PIN Priority. If this is not configured, the SDK will process Visa tranasction with the CDCVM priority. For more information, refer to Configure Visa CVM priority.

You may define a custom name for the configuration PLIST file, for example: "YourPlistName.plist". The custom name may be provided via SDK initialisation.

By default, NFC Wallet SDK will search for TSHPay.plist in the main bundle of the application if the mobile application does not provide any.

The following examples shows how to initialise the SDK using the default TSHPay.plist

Task {
    do {
        try await TSHPay.shared.configure(withVerificationMethod: .userPresence)
    } catch let error as TSHPaySDK.TSHPay.Error {
        switch error {
        case .storageUnrecoverableError:
            do {
                try await TSHPay.shared.reset()
                try await TSHPay.shared.configure(withVerificationMethod: .userPresence)
            } catch {
                // Handle the error.
            }
            
        default: break
            // Handle other errors.
        }
    }
}

Check device eligibility

After SDK inititalization, verify the device eligibility to check:

• Device owner authentication method using deviceEligibility.
• Contactless payment capability using contactlessPaymentEligibility.

If the device meets the requirements, the SDK returns supported.

func checkDeviceEligibility() {
    Task {
        let eligibility = await TSHPay.shared.deviceEligibility
        switch eligibility.deviceOwnerAuthentication {
        case .supported:
            // Device is eligible. You can start Tokenization.
        case .passcodeNotSet:
            // Ask the End User to set a device passcode.
        case .biometricNotSet:
            // Ask the End User to enroll biometrics (Touch ID / Face ID).
        }
    }
}

Retrieving the Wallet ID

Use TSHPay.walletID to retrieve the wallet identifier.

The SDK generates the wallet ID the first time you call TSHPay.configure.

The wallet ID remains stable across application restarts.

If you reset the SDK, the wallet ID is regenerated.

Use the wallet ID for troubleshooting and support.

let walletIdentifier = TSHPay.walletID
print("Retrieved wallet ID: \(walletIdentifier)")