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

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.

Default payment application

Android lets the end user choose the default payment application for Tap & Pay.

Example: default payment application setting

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

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.

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.
• If not, prompt the end user to set your app as the default payment service by launching CardEmulation#ACTION_CHANGE_DEFAULT.

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:

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 and CardEmulation#unsetPreferredService following the Android guidelines.

The Activity passed to setPreferredService(...) must be in a resumed state.

Call setPreferredService(...) in Activity#onResume.

Call unsetPreferredService(...) in Activity#onPause.

Use CardEmulation#categoryAllowsForegroundPreference to detect whether foreground preference is allowed for the payment category.

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 .