Enroll wallet

Overview

Enroll your digital wallet application after NFC Wallet SDK initialization and before you start Tokenization. Wallet enrollment provisions the digital wallet application with the security assets required to call NFC Wallet services:

• Run this once per wallet instance.

• Run this only if the digital wallet application uses NFC Wallet services.

• Run this only on devices that support contactless payments. See Check contactless capability.

Enroll only digital wallet applications that use NFC Wallet services.

This avoids unnecessary network traffic from the digital wallet application and unnecessary load on NFC Wallet product.

Sequence diagram

High-level flow to enroll your wallet application.

Wallet enrollment flow.

This flow is technically called wallet secure enrollment in NFC Wallet.

SDK Integration

Prerequisites

Before you start, verify the following:

• Your digital wallet application is onboarded in the NFC Wallet backend.

• You initialized the NFC Wallet SDK.

• The wallet is not enrolled (WalletSecureEnrollmentService.isEnrolled() returns false).

• If you support contactless payments, confirm the device is eligible. See Check contactless capability.

Skip contactless capability check if your digital wallet application does not support contactless payments (for example, QR code or DSRP remote payment only).

Perform wallet enrollment

Wallet enrollment is a one-time action in the digital wallet application lifecycle.

Run it after SDK initialization, and only if the wallet is not enrolled.

1. Create a WalletSecureEnrollmentService instance.

2. Check wse.isEnrolled().

3. If needed, call wse.enroll() to start the process. If the operation is successful, the wallet secure enrollment is completed, otherwise, an error will be thrown.

After wallet secure enrollment completes successfully, continue with Tokenize a card.

func invokeWSEAsync() async {
   do {
        let wse = try WalletSecureEnrollmentService()
        // Check wallet enrollment status.
        if wse.isEnrolled() {
            // WSE is enrolled
        } else {
            // Trigger wallet secure enrollment.
            try await wse.enroll()
            // Enrollment process is completed successfully here.
        }
    } catch {
        // WSE error 
    }
}

Errors

When wallet enrollment fails, handle these error types:

• clientError: An internal SDK error. A message is provided to the digital wallet application.

• serverError: A backend error. A message, httpStatus, errorCode, and optional additionalInfo are provided to the digital wallet application.

• networkError: The device has no internet connection.

The WalletSecureEnrollmentService.eventStream and WalletSecureEnrollmentService.State APIs are deprecated and will be removed in the next release. Hence, you have to migrate your code to use the WalletSecureEnrollmentService.enroll API and for all new implementations as demonstrated above

Deprecated APIs

The following example demonstrates the use of WalletSecureEnrollmentService.State and WalletSecureEnrollmentService.eventStream APIs which are deprecated.

These are the possible events of WalletSecureEnrollment when the WalletSecureEnrollmentService.eventStream (deprecated) API is used:

• .started: Wallet secure enrollment process is started.

• .completed : Wallet secure enrollment process is completed.

• .errorEncountered: The wallet secure enrollment error is returned.

// Deprecated API
func invokeWSEAsync() async {
    do {
        let wse = try WalletSecureEnrollmentService()
        // check wallet enrollment status.
        if wse.isEnrolled() {
            // WSE is enrolled
        } else {
          // trigger wallet secure enrollment.
            wse.enroll()
            for await state in wse.eventStream {
              switch state {
                case .started:
                  // trigger when WSE started.
                case .completed:
                  // trigger when WSE completed.
                case .errorEncountered(let error):
                  switch error {
                    case .clientError(let message):
                        //error handling 
                    case .serverError(let message, let httpStatus, let errorCode, let additionalInfo):
                        //error handling 
                    case .networkError:
                        //error handling 
                    }
                }
            }
        }
    } catch {
        // WSE initialization error 
    }
}