Create a secure device wallet

To enable NFC payments on a device, the customer’s account must be digitized and provisioned into the user's device. For this process, our SDK creates a secure device wallet, which is a wrapper within the device that stores the tokens securely.

Provisioning is a one-time activity that occurs during the initial setup after installation. For subsequent logins, the already provisioned secure device wallet will be utilized.

note

All the secure device wallet provisioning methods are asynchronous. The app needs to listen to the respective callbacks to receive the response. For a more complete example, please refer to the MainActivity.kt file from the provided reference application.

Initialize the SDK

To start using the SDK, first you need to call OfNfcSdk.init(), ideally in the Activity#onCreate() callback prior to using it.

MainActivity.kt

override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)
  OfNfcSdk.init(this.application)
}

Check if the secure device wallet is provisioned

Before creating a new secure device wallet, you should check if the device already has a secure device wallet created. This will automatically happen when you invoke WalletManager#connect() method within the onResume() lifecycle.

MainActivity.kt

private val walletManager by lazy {
  OfNfcSdk.getWalletManager(this.applicationContext, this as WalletManagerCallback)
}

override fun onResume() {
  super.onResume()
  walletManager.connect()
}

connect() call is asynchronous and triggers one of the wallet manager callbacks being called by the SDK, allowing your app to know in which state the secure device wallet is:

1. WalletManagerCallback#onConnectionSuccess() is called when the secure device wallet is already provisioned in the device, and the user can access the functionalities of the secure device wallet. This may mean the secure device wallet exists. Use wallet.cards() method to verify the presence of any configured cards in the secure device wallet. If any card with CardStatus.ACTIVATED is detected, the device is ready for NFC payment. Otherwise, proceed to Tokenizing a customer account to now digitize a customer’s account and move from there.
2. WalletManagerCallback#onProvisioningRequired() is called when secure device wallet access is refused because there is no wallet currently initialized in the app. This will be the case for all new devices where we are setting them up for NFC payment. You can now proceed to the next section Initialize provisioning to start the provisioning process.
3. WalletManagerCallback#onConnectionError() is called when secure device wallet access cannot be made, for a specific reason provided as a method argument.

MainActivity.kt

override fun onProvisioningRequired() {
  displayProvisioning();
}

override fun onConnectionError(
  error: OpenFabricError
) {
  displayError(RuntimeException(error.message))
}

override fun onConnectionSuccess(wallet: Wallet) {
  redirectToApp()
}

Initialize provisioning

Now that we have determined that a secure device wallet is not already provisioned on the device, we can start with the process to create one. To start the process you have to call walletProvisioning.initialize() method.

Initialization is an asynchronous operation during which our SDK checks device OS compatibility and the status of the permissions mandatory for its proper execution.

initialize() function triggers any one of the following wallet provisioning callbacks:

1. WalletProvisioningCallback#onInitializationSuccess() is called when initialization has succeeded.
2. WalletProvisioningCallback#onInitializationError() is called when initialization has failed for a specific reason and provisioning can’t proceed on the device.

Initialize Provisioning

val callback = object : WalletProvisioningCallback {
  ...
  override fun onInitializationSuccess() {
    walletProvisioning.checkEligibility(true)
  }

  override fun onInitializationError(
    error: OpenFabricError
  ) {
    displayError(RuntimeException(error.message))
  }
}

val walletProvisioning by lazy {
  OfNfcSdk.getWalletProvisioning(this.applicationContext, callback)
}


walletProvisioning.initialize()

Device eligibility check

Our SDK requires you to perform an eligibility check using walletProvisioning.checkEligibility() method before creating a secure device wallet. A device is considered eligible if it meets the security requirements (i.e. the Android OS version is supported, device is not rooted / running secure firmware, the SDK library integrity is intact and the required device features are supported).

checkEligibility() function triggers any one of the following wallet provisioning callbacks:

1. WalletProvisioningCallback#onDeviceEligible() is called when the device has been considered as eligible.
2. WalletProvisioningCallback#onDeviceNotEligible() is called when the device has been considered as not eligible, thus secure device wallet provisioning is not possible on it.
3. WalletProvisioningCallback#onCheckEligibilityError() is called if the eligibility check has failed, for a specific reason provided as method argument.

Device eligibility Check

override fun onDeviceEligible(
) {
  walletProvisioning.provision(walletSettingsProfileId)
}

override fun onDeviceNotEligible(
  reason: Array<String>?
) {
  displayError(RuntimeException(reason?.joinToString(", ")))
}

override fun onCheckEligibilityError(
  error: OpenFabricError,
) {
  displayError(RuntimeException(error.message))
}

Start provisioning

Secure device wallet provisioning is triggered by calling the WalletProvisioning.provision() method. It triggers one of the following wallet provisioning callbacks:

1. WalletProvisioningCallback#onProvisioningSuccess() is called when the secure device wallet has been provisioned successfully into this app. This means the secure device wallet is successfully provisioned and can proceed to Tokenizing a customer account.
2. WalletProvisioningCallback#onProvisioningError() is called when provisioning fails for a specific reason provided as a method argument.