Enroll wallet

Overview

Enroll the 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 use 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 eligible devices.

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.

Sequence diagram

High-level flow to enroll your wallet application.

Wallet enrollment high-level 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 (see below).

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. Get a WalletSecureEnrollmentBusinessService instance.
2. Check getState() returns WSE_REQUIRED.
3. If needed, call startWalletSecureEnrollment() to start wallet enrollment.
4. Implement WalletSecureEnrollmentListener to track progress.

These are the possible callbacks:

• onProgressUpdate with state WSE_STARTED: The process starts.
• onProgressUpdate with state WSE_COMPLETED: The process completes successfully.
• onError: The process fails with an error.

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

public void performWseIfNeeded() {
    // First check current status. Whether we need WSE at all.
    final WalletSecureEnrollmentBusinessService wseService 
                = ProvisioningServiceManager.getWalletSecureEnrollmentBusinessService();
    final WalletSecureEnrollmentState state = wseService.getState();

    switch (state) {
        case WSE_COMPLETED:
        case WSE_NOT_REQUIRED:
            // WSE was already done in current or some previous instance.
            break;
        case WSE_STARTED:
            // WSE was triggered during this instance. Simple wait for the first one to finish.
            return;
        case WSE_REQUIRED:
            // Trigger WS enrollment.
            wseService.startWalletSecureEnrollment(new WalletSecureEnrollmentListener() {
                @Override
                public void onProgressUpdate(final WalletSecureEnrollmentState wseState) {
                    if (wseState == WalletSecureEnrollmentState.WSE_COMPLETED) {
                        // Success
                    }
                    else if (wseState == WalletSecureEnrollmentState.WSE_STARTED) {
                        // Started
                    }
                }

                @Override
                public void onError(final WalletSecureEnrollmentError wbDynamicKeyRenewalServiceError) {
                    // Log error
                }
            });
            break;
        default:
            // Log error as it should not happen
            break;
    }
}   

Error code details

When WalletSecureEnrollmentListener.onError(...) is triggered, the SDK provides a WalletSecureEnrollmentError.

It includes an error code and a message, plus additional fields depending on the failure type.

Parse WalletSecureEnrollmentError

The structure of the WalletSecureEnrollmentError object is as follows:

• SDK error code: The error type for this operation.
• CPS error code: The numeric error code returned by the CPS module (server-side).
• HTTP status code: The HTTP status code returned for communication errors.
• Message: A human-readable error description.

The error needs to be parsed as follows:

1. Read getSdkErrorCode() to get a WalletSecureEnrollmentErrorCodes value.
2. If the SDK error code indicates a communication error (COMM_ERROR), read getHttpStatusCode().
3. If the SDK error code indicates a server-side error (SERVER_ERROR), read getCpsErrorCode().
4. Read getErrorMessage() for log-friendly description.
5. If the SDK error code is DEVICE_SUSPICIOUS, read getStatusAdditionalInfo() and log it for troubleshooting.

Refer to WalletSecureEnrollmentErrorCodes in the Android API reference for the full list of codes.

WalletSecureEnrollmentErrorCodes

Use the following recommendations to decide whether to retry, stop, or reset the SDK.

Call SDKDataController.wipeAll() when the recommendation is to reset the SDK.

Error code tables

Error code	When it happens	Recommended action
WSE_INTERNAL_ERROR	An internal SDK error occurs.	Retry wallet enrollment. If the issue persists, reset the SDK.
COMMON_NO_INTERNET	The device has no network connectivity.	Ask the end user to connect to a network, then retry wallet enrollment.
COMMON_COMM_ERROR	A communication error occurs while retrieving security assets.	Retry wallet enrollment.
COMMON_SERVER_ERROR	A server-side error occurs while retrieving security assets.	Retry wallet enrollment. If the issue persists, contact the Thales delivery team to validate the environment setup.
RE_ENROLLMENT_REQUIRED	Re-enrollment is required for security reasons.	Reset the SDK, then run wallet enrollment again.
WSE_STORAGE_ACCESS_ERROR	The SDK exceeds its internal retry limit when accessing secure storage.	Reset the SDK, then retry wallet enrollment.
JSON_PARSING_ERROR	The response data cannot be parsed.	Retry wallet enrollment. If the issue persists, reset the SDK.
WSE_REQUEST_ERROR	The enrollment request fails.	Retry wallet enrollment.
WSE_DOWNLOAD_ERROR	The security asset download fails.	Verify network connectivity, then retry wallet enrollment.
WSE_ERROR_INIT_SESSION	WSE session initialization fails (typically authentication-related).	Retry wallet enrollment.
WSE_ERROR_COMPUTE_AUTH_VALUE_FAILED_PACKAGE_NOT_FOUND	The SDK cannot compute the authentication value because the package name cannot be resolved.	Verify the application package name used in your onboarding configuration, then retry wallet enrollment.
WSE_ERROR_COMPUTE_AUTH_VALUE_FAILED_CERT_EXCEPTION	The SDK cannot compute the authentication value due to an application signing or public key issue.	Verify the application signing certificate used in your onboarding configuration, then retry wallet enrollment.
WSE_CPS_COMPONENT_NOT_INITIALIZED	Wallet enrollment starts before the CPS component is initialized.	Initialize the SDK, then retry wallet enrollment.
WSE_MG_COMPONENT_NOT_INITIALIZED	Wallet enrollment starts before the MobileGateway component is initialized.	Initialize the SDK, then retry wallet enrollment.
DEVICE_SUSPICIOUS	The SDK detects a device security threat.	Stop the flow and inform the end user that the device cannot be used. Capture and share getStatusAdditionalInfo() when contacting Thales support.
WSE_KCV_ERROR	The SDK fails to validate downloaded security assets (KCV check fails).	Retry wallet enrollment.

Application binding key (notes)

As described in onboarding you must provide the application binding key.

If the application binding key is not provided or incorrect, enroll wallet will failed.

Please check warning and note below.

Signing key rotation / Multiple signers

If the oldest signing key is not provided as the first signer value in the proof-of-rotation struct, then enroll wallet will fail

Downgrading to earlier versions of NFC Wallet SDK

To downgrade to an earlier version of NFC Wallet SDK, the application has to ensure that the oldest signing key is provided as the first signer in the proof-of-rotation struct.