4. Initialize the NFC Wallet SDK

Initialize the NFC Wallet SDK

Initialize the NFC Wallet SDK before you call any other SDK API.

Recommended flow:

1. Add the required properties files.
2. Build a CustomConfiguration.
3. (Optional) Call SDKInitializer.INSTANCE.configure(...) during app startup.
4. Call SDKInitializer.INSTANCE.initialize(...) on a background thread.
5. Call MobileGatewayManager.INSTANCE.configure(...) to configure Mobile Gateway (MG).

Check Android version

Verify the Android version meets the minimum NFC Wallet Android SDK requirements before initializing the SDK.

Hide NFC Wallet features for unsupported Android versions.

Add the required properties files

Create the following files in your Android digital wallet application assets folder:

• mobilegateway.properties
• rages.properties
• gemcbp.properties

Set the values provided by Thales (unless a value is explicitly marked as fixed below).

mobilegateway.properties

mobilegateway.properties description

Key	Description
MG_CONNECTION_URL	[String] URL of the MG server (provided by Thales).
MG_TRANSACTION_HISTORY_CONNECTION_URL	[String] URL for retrieving transaction history (provided by Thales).
WALLET_PROVIDER_ID	[String] Wallet provider ID.
WALLET_APPLICATION_ID	[String] Wallet provider application ID (Optional). Required when the wallet provider supports multiple wallet applications.
MG_CONNECTION_TIMEOUT	[Integer] Connection timeout in milliseconds. Recommended: 30000.
MG_CONNECTION_READ_TIMEOUT	[Integer] Read timeout in milliseconds. Recommended: 30000.
MG_RETRY_COUNTER	[Integer] Number of retries. Recommended: 3.
MG_RETRY_INTERVAL	[Integer] Interval in milliseconds between retries. Recommended: 10000.

rages.properties

rages.properties description

Key	Description
REALM	[String] Fixed value: CBP.
OAUTH_CONSUMER_KEY	[String] OAuth consumer key (provided by Thales).
RAGES_GATEWAY_URL	[String] RAGES gateway URL (provided by Thales).
RAGES_CONNECTION_TIMEOUT	[Integer] Connection timeout in milliseconds. Recommended: 30000.
CSR_DOMAIN	[String] Domain used in the certificate signing request (CSR) for HTTPS. Ask the Thales delivery team for the value.
CSR_EMAIL	[String] Company email address.

gemcbp.properties

gemcbp.properties description

Key	Description
CPS_URL	[String] CPS URL (provided by Thales).
CPS_CONNECTION_TIMEOUT	[Integer] Connection timeout in milliseconds. Recommended: 30000.
CPS_READ_TIMEOUT	[Integer] Read timeout in milliseconds. Recommended: 30000.

Configure payment behavior

CustomConfiguration defines payment behavior:

• keyValidityPeriod: Time (in seconds) between end user authentication and the tap on the POS terminal. Range: 0–300. Default: 45.
• domesticCurrencyCode: ISO 4217 numeric currency code used for CDCVM during LVT (Low Value Transaction) payments. Default: 978 (EUR).

CustomConfiguration supports additional risk management and CDCVM parameters. See Define risk management.

We recommend reviewing these parameters when implementing contactless payment.

The SDK uses CustomConfiguration during initialization.

/* Initialize SDK with different values than default */
CustomConfiguration customConfig = new CustomConfiguration.Builder()
                .domesticCurrencyCode(978)
                .keyValidityPeriod(60)
                .build();

Do not change keyValidityPeriod and domesticCurrencyCode after the first initialization.

Changes can introduce delays and intermittent issues between authentication and the final tap at the POS terminal.

Run SDK quick configuration (optional)

Use SDKInitializer.INSTANCE.configure(...) to preload the Android Context, CustomConfiguration, and native libraries.

After configure(...) completes, you can call APIs that only read local SDK storage.

See SDK API requirements for details.

configure() does not run SDK migration. If migration is required, it runs during initialize().

MyApp.java

public class MyApp extends Application {

    @Override
    public void onCreate() {
        super.onCreate();

        try {
            // 1. Build your CustomConfiguration (see above).
            ...

            // 2. Run quick configuration to ensure the SDK has an Android Context.
            SDKInitializer.INSTANCE.configure(this, customConfig);
        } catch (InternalComponentException e) {
            // You can log and continue with initialize().
        } catch (Exception e) {
            // Safeguard against crashes during Application startup.
            // You can log and continue with initialize().
        } catch (Throwable e) {
            // This is unlikely.
            // If it happens, do not call initialize().
            return;
        }

        // 3. Initialize the SDK asynchronously so Application startup is not blocked.
        // See "Initialize the SDK (payment)" below.
    }
}

Initialize the SDK (payment)

Check the SDK state using SDKController.getInstance().getSDKServiceState() and only initialize when needed.

Use SDKInitializer.INSTANCE.initialize(...) to initialize the payment components:

• Provide CustomConfiguration as an input parameter.
• This API is synchronous. Call it from a background thread.

Initialize the NFC Wallet SDK (Java)

final Context appContext = getApplicationContext();

if (SDKController.getInstance().getSDKServiceState() != SDKServiceState.STATE_INITIALIZED) {
    Thread sdkInit = new Thread(new Runnable() {
        @Override
        public void run() {
            SDKInitializer.INSTANCE.initialize(appContext, customConfig);
        }
    });
    sdkInit.start();
}

The initialization APIs are idempotent. You can call them multiple times safely.

Configure Mobile Gateway (MG)

After SDK initialization completes, call MobileGatewayManager.INSTANCE.configure(...) to enable Tokenization, digital card LCM, and transaction history.

Use MobileGatewayManager.INSTANCE.getConfigurationState() to check configuration state.

Configure Mobile Gateway (Java)

protected void initMgSdk(@NonNull final Context context) {
    final MobileGatewayManager mgManager = MobileGatewayManager.INSTANCE;

    try {
        // Avoid multiple initialization.
        if (mgManager.getConfigurationState() == MGSDKConfigurationState.NOT_CONFIGURED) {
            mgManager.configure(context);
        }
    } catch (final MGConfigurationException exception) {
        // Log error.
    }
}

Retrieve the wallet ID

Use getWalletId() from MGCardEnrollmentService to retrieve the wallet identifier.

Retrieve the wallet ID (Java)

MGCardEnrollmentService enrollService = MobileGatewayManager.INSTANCE.getCardEnrollmentService();
String walletId = enrollService.getWalletId();

MGSDKException is thrown if an error occurs while retrieving the wallet ID.

Use the wallet ID for troubleshooting and support.

The SDK generates the wallet ID the first time you initialize the SDK:

• The wallet ID remains stable across application restarts.
• If you reset the SDK, the wallet ID is regenerated.