> For the complete documentation index, see [llms.txt](https://docs.payments.thalescloud.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.payments.thalescloud.io/nfc-wallet-sdk-android/get-started/configuration/4.-initialize-the-nfc-wallet-sdk.md).

# 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)**.

{% hint style="warning" %}

## 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.
{% endhint %}

### 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

<details>

<summary>mobilegateway.properties description</summary>

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

</details>

#### rages.properties

<details>

<summary>rages.properties description</summary>

<table><thead><tr><th width="353">Key</th><th>Description</th></tr></thead><tbody><tr><td>REALM</td><td>[String] Fixed value: <strong>CBP</strong>.</td></tr><tr><td>OAUTH_CONSUMER_KEY</td><td>[String] OAuth consumer key (provided by Thales).</td></tr><tr><td>RAGES_GATEWAY_URL</td><td>[String] RAGES gateway URL (provided by Thales).</td></tr><tr><td>RAGES_CONNECTION_TIMEOUT</td><td>[Integer] Connection timeout in milliseconds. Recommended: 30000.</td></tr><tr><td>CSR_DOMAIN</td><td>[String] Domain used in the certificate signing request (CSR) for HTTPS. Ask the Thales delivery team for the value.</td></tr><tr><td>CSR_EMAIL</td><td>[String] Company email address.</td></tr></tbody></table>

</details>

#### gemcbp.properties

<details>

<summary>gemcbp.properties description</summary>

<table><thead><tr><th width="353">Key</th><th>Description</th></tr></thead><tbody><tr><td>CPS_URL</td><td>[String] CPS URL (provided by Thales).</td></tr><tr><td>CPS_CONNECTION_TIMEOUT</td><td>[Integer] Connection timeout in milliseconds. Recommended: 30000.</td></tr><tr><td>CPS_READ_TIMEOUT</td><td>[Integer] Read timeout in milliseconds. Recommended: 30000.</td></tr></tbody></table>

</details>

### 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](https://en.wikipedia.org/wiki/ISO_4217) used for CDCVM during LVT (Low Value Transaction) payments. Default: 978 (EUR).

{% hint style="info" %}
`CustomConfiguration` supports additional risk management and CDCVM parameters. See [Define risk management](/nfc-wallet-sdk-android/implement-nfc-wallet/make-payment/implement-contactless-payments/7.-configure-cdcvm-experiences/define-risk-management.md).

We recommend reviewing these parameters when implementing contactless payment.
{% endhint %}

The SDK uses `CustomConfiguration` during initialization.

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

{% hint style="warning" %}
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.
{% endhint %}

### 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](/nfc-wallet-sdk-android/help/sdk-api-requirements.md) for details.

{% hint style="info" %}
`configure()` does not run SDK migration. If migration is required, it runs during `initialize()`.
{% endhint %}

{% code title="MyApp.java" expandable="true" %}

```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.
    }
}
```

{% endcode %}

### 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.

{% code title="Initialize the NFC Wallet SDK (Java)" %}

```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();
}
```

{% endcode %}

{% hint style="info" %}
The initialization APIs are idempotent. You can call them multiple times safely.
{% endhint %}

### 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.

{% code title="Configure Mobile Gateway (Java)" %}

```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.
    }
}
```

{% endcode %}

### Retrieve the wallet ID

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

{% code title="Retrieve the wallet ID (Java)" lineNumbers="true" %}

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

{% endcode %}

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

{% hint style="info" %}
Use the wallet ID for troubleshooting and support.
{% endhint %}

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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.payments.thalescloud.io/nfc-wallet-sdk-android/get-started/configuration/4.-initialize-the-nfc-wallet-sdk.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.