> 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/help/knowledge-base/control-nfc-payments-on-android.md). # Control NFC payments on Android ## Overview Android system settings can block contactless payments, even when your **digital wallet application** is correct. This page covers the Android controls that impact NFC payments, plus the app-side requirements to support them. ## Device settings that affect NFC payments ### NFC toggle Android provides a master NFC switch, similar to Wi‑Fi or mobile data. NFC must be enabled to execute contactless payments. End users can also disable NFC to block payments.

Example: NFC toggle in Quick Settings

### Require device unlock (Android 12+) On some devices (Android 12+), NFC can be configured to work only when the device is unlocked. If enabled, the end user must unlock the device before tapping.

Example: option to require an unlocked device for NFC

### Application source selection (OEM-specific) Some devices support multiple “payment locations” (for example, secure element vs HCE). The device hardware routes inbound NFC commands to the selected location.

Example: application source selection for contactless payments

{% hint style="info" %} The NFC Wallet SDK uses host-based card emulation (HCE). If the device exposes an application source setting, instruct end users to select an option equivalent to **HCE Wallet**. {% endhint %} ### Default payment application Android lets the end user choose the default payment application for Tap & Pay.

Example: default payment application setting

{% hint style="info" %} Some devices also show a switch such as **Pay with currently open app**. This requires app-side support. See [Support “Pay with currently open app”](#support-pay-with-currently-open-app). {% endhint %} ## Digital wallet application requirements (HCE) Your **digital wallet application** must declare an HCE service. The NFC Wallet SDK does not declare the HCE service for you. It provides `AbstractHCEService` to simplify implementation. For background, see [Host-based card emulation overview](https://developer.android.com/guide/topics/connectivity/nfc/hce). ### Detect and request the default payment application At startup, it is recommended to: * Check whether your HCE service is the default one, using [CardEmulation#isDefaultServiceForCategory](https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#isDefaultServiceForCategory\(android.content.ComponentName,%20java.lang.String\)). * If not, prompt the end user to set your app as the default payment service by launching [CardEmulation#ACTION\_CHANGE\_DEFAULT](https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#ACTION_CHANGE_DEFAULT). ```java Intent intentSetDefaultTapNPay = new Intent(); intentSetDefaultTapNPay.setAction(ACTION_CHANGE_DEFAULT); intentSetDefaultTapNPay.putExtra(EXTRA_SERVICE_COMPONENT, new ComponentName(this, CANONICAL_PAYMENT_SERVICENAME)); intentSetDefaultTapNPay.putExtra(EXTRA_CATEGORY, CATEGORY_PAYMENT); startActivity(intentSetDefaultTapNPay); ``` Android displays a system dialog. You cannot change its text, except for your app label.

Example: Android dialog to change the default payment app

To observe the user’s choice, call `startActivityForResult` and check the result in `onActivityResult`: ```java private void checkAndSetTapNPayDefault() { // ... startActivityForResult(intentSetDefaultTapNPay, REQ_CODE_TAP_N_PAY_SET_DEFAULT); } @Override public void onActivityResult(final int requestCode, final int resultCode, final Intent data) { if (requestCode == REQ_CODE_TAP_N_PAY_SET_DEFAULT) { if (resultCode == RESULT_OK) { // user selected 'Replace' } else { // user selected 'No' } } } ``` ### Control how your app appears in Android settings The Tap & Pay / Contactless payments UI varies by OEM, model, and Android version.

Example: Tap & Pay UI differences across devices

Android populates your application entry using resources from: * `AndroidManifest.xml` * Your payment service metadata resource (declared via `/manifest/application/service/meta-data/@android:resource`) You can control: * **Application icon**: `/manifest/application/@android:icon` * **Payment service banner**: payment service metadata, `/host-apdu-service/@android:apduServiceBanner` * **Payment service label**: `/manifest/application/service/@android:label` * This label is also used in the “set default payment app” dialog. * **Payment service description**: payment service metadata, `/host-apdu-service/@android:description` You cannot control the ordering of applications in the list. ### Pay with foreground app Some devices expose a setting such as **Pay with currently open app** or **Prioritize currently running app**. This setting only means the end user allows foreground apps to override the default payment service. It does not enforce that behavior. To take advantage of it, implement [CardEmulation#setPreferredService](https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#setPreferredService\(android.app.Activity,%20android.content.ComponentName\)) and [CardEmulation#unsetPreferredService](https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#unsetPreferredService\(android.app.Activity\)) following the Android guidelines. {% hint style="info" %} The `Activity` passed to `setPreferredService(...)` must be in a resumed state. Call `setPreferredService(...)` in [Activity#onResume](https://developer.android.com/reference/android/app/Activity#onResume\(\)). Call `unsetPreferredService(...)` in [Activity#onPause](https://developer.android.com/reference/android/app/Activity#onPause\(\)). Use [CardEmulation#categoryAllowsForegroundPreference](https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#categoryAllowsForegroundPreference\(java.lang.String\)) to detect whether foreground preference is allowed for the payment category. {% endhint %} Recommendations: * Check that foreground preference is enabled using `CardEmulation.categoryAllowsForegroundPreference(CATEGORY_PAYMENT)`. * Implement the default application override as explained earlier. * Warn end users about inconsistent payment experience if your digital wallet application handles contacless transaction only when it is in foreground . --- # 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, and the optional `goal` query parameter: ``` GET https://docs.payments.thalescloud.io/nfc-wallet-sdk-android/help/knowledge-base/control-nfc-payments-on-android.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.