Trigger provisioning

Overview

After you digitize a card, start a provisioning session to provision the digital card.

During the provisioning session, the NFC Wallet provisions securly the digital card profile and payment keys in your digital wallet application.

Start the provisioning session right after you receive the activationCode from MGDigitizationListener.onCPSActivationCodeAcquired. See Digitize a card.

This callback also returns digitalCardId. Store it for later operations (for example, access tokens, transaction history, and LCM). You do not need it to start secure provisioning.

This step also sets up the secure channel between the NFC Wallet SDK and the NFC Wallet backend.

This setup is called device enrollment (also known as CPS enrollment).

Sequence diagram

Secure provisioning flow (device enrollment and provisioning session).

SDK integration

Secure provisioning requires device enrollment.

Device enrollment is typically required once per wallet instance on a device. When enrollment is required, the enrollment flow triggers the provisioning session automatically.

If device enrollment is already complete, start the provisioning session by calling ProvisioningBusinessService.sendActivationCode(...).

The SDK requests the activationCode through EnrollingServiceListener.onCodeRequired(...). Provide the value at that time.

Prerequisites

Before you start, make sure you have:

• Initialized the NFC Wallet SDK. See Initialize the NFC Wallet SDK.
• Configured push notifications and retrieved a push token. See Push notifications.
• Received the activationCode from digitization. See Digitize a card.

Device enrollment

Device enrollment requires these inputs:

• activationCode (byte[]): Returned by digitization.
• walletId: Retrieve using MGCardEnrollmentService.getWalletId(). Pass this value as the userId parameter to EnrollingBusinessService.enroll(...). See Retrieve the wallet ID.
• pushToken: The push token for FCM or HMS Push Kit.

Prefix HMS Push Kit tokens with HMS: (for example, HMS:<token>).

Check device enrollment status

Check the device enrollment status using EnrollingBusinessService.isEnrolled().

This status indicates whether the secure channel is already established for the current wallet instance on this device.

It returns an EnrollmentStatus:

• ENROLLMENT_NEEDED: Call EnrollingBusinessService.enroll(...).
• ENROLLMENT_IN_PROGRESS: Call EnrollingBusinessService.continueEnrollment(...).
• ENROLLMENT_COMPLETE: Call ProvisioningBusinessService.sendActivationCode(...).

Implement EnrollingServiceListener

Implement EnrollingServiceListener to drive the enrollment flow:

• onCodeRequired: Provide the activationCode.
• onComplete: Device enrollment completes successfully.
• onError: Handle errors using ProvisioningServiceError.

MyEnrollingServiceListener.java

public class MyEnrollingServiceListener implements EnrollingServiceListener {

    // Receive from MGDigitizationListener.onCPSActivationCodeAcquired(...)
    private final byte[] activationCode;

    public MyEnrollingServiceListener(final byte[] activationCode) {
        this.activationCode = activationCode;
    }

    @Override
    public void onStarted() {
        // Called when the enrollment flow starts.
    }

    @Override
    public void onCodeRequired(final CHCodeVerifier chCodeVerifier) {
        // Called when the activation code is required to continue the flow.
        final SecureCodeInputer inputer = chCodeVerifier.getSecureCodeInputer();
        for (final byte b : activationCode) {
            inputer.input(b);
        }
        inputer.finish();
    }

    @Override
    public void onComplete() {
        // Called once the device enrollment completes successfully.
        // In a Green flow, this usually means provisioning is complete.
    }

    @Override
    public void onError(final ProvisioningServiceError error) {
        // Called when device enrollment fails.
        // Parse error.getCode() and apply the right retry / recovery logic.
    }
}

Device enrollment code implementation

byte[] activationCode = ...; // from MGDigitizationListener.onCPSActivationCodeAcquired(...)
String pushToken = "..."; // from FCM or HMS Push Kit
String language = "en"; // Use your app locale when possible.

// Wallet ID is the user identifier for device enrollment.
String walletId = MobileGatewayManager.INSTANCE.getCardEnrollmentService().getWalletId();

EnrollingServiceListener enrollingListener = new MyEnrollingServiceListener(activationCode);

final EnrollingBusinessService enrollingService = ProvisioningServiceManager.getEnrollingBusinessService();
final ProvisioningBusinessService provisioningBusinessService = ProvisioningServiceManager.getProvisioningBusinessService();

// Check enrollment status.
final EnrollmentStatus status = enrollingService.isEnrolled();
switch (status) {
    case ENROLLMENT_NEEDED:
        // First device enrollment attempt on this wallet instance.
        enrollingService.enroll(walletId, pushToken, language, enrollingListener);
        break;
    
    case ENROLLMENT_IN_PROGRESS:
        // Enrollment was started earlier and must be resumed.
        enrollingService.continueEnrollment(language, enrollingListener);
        break;
    
    case ENROLLMENT_COMPLETE:
        // Device enrollment is already completed.
        // Trigger provisioning for this card.
        // The SDK requests the activation code via enrollingListener.onCodeRequired(...).
        provisioningBusinessService.sendActivationCode(enrollingListener);
        break;
    
    default:
        // Log error (unknown status).
 }