Tap to Pay on Android — FAQ

Getting Started

Q: What is Tap to Pay on Android?
A: Tap to Pay lets merchants accept contactless cards and Google Pay on a compatible Android phone or tablet without a separate card reader. NMI offers two ways to use it:

Option 1: Cloud Commerce app

1. Enable Tap to Pay on the merchant account: Partner Portal → List Accounts → select merchant → Value-Added Services → Update Services → set Tap to Pay to Active → Submit. Setting it to Offered is not enough.
2. Download Cloud Commerce from Google Play.
3. Turn off Bluetooth and unplug any peripherals.
4. Open the app and enter the NMI partner code: CC_8bFEes1a
5. Log in with the merchant's NMI Merchant Portal credentials.
6. Allow location and microphone permissions when prompted.

Option 2: Tap to Pay SDK

Your app must complete a one-time onboarding before it works, including in test. Testing (MTF) and production are separate onboardings. Start as early as possible; each takes 2–3 weeks.

Email [email protected] with everything below in one message:

Who submits: the company building the integrating app. If you're an ISV working with an NMI partner, you submit the request yourself.

Onboarding is per app, not per merchant. Mastercard registers your package name and signing certificate. Once your app is onboarded, any merchant gateway with Tap to Pay set to Active can use it, with no further registration per merchant.

Environments — read this first

Q: Which settings need to match?
A: Every part of your setup must point at the same environment. If any one of them differs, connectAndConfigure() fails before a card is read.

Q: Which NMI account should I test with?
A: Either a sandbox account or a live gateway switched to Test Mode. In both cases, set Tap to Pay to Active first (Partner Portal → merchant → Value-Added Services → Update Services), and pair the account with MTF onboarding and the sandbox Cloud Commerce AAR. Never point the SDK's test environment at a live gateway that isn't in Test Mode.

Note: if you use a live gateway, all of its traffic while it's in Test Mode is processed as test transactions. Don't use a gateway that is processing live payments.

Signing certificates

Q: Which certificate do I register?
A: The one that signs the APK actually installed on the test device:

• Installed from Google Play (any track, including Internal Testing): the Play App Signing certificate (Play Console → Setup → App signing). Don't use your upload key; Google re-signs your app with its own key.
• Sideloaded debug or local build: the key that signed that build, usually your debug keystore.

If your debug and release builds use different keys, register both, one for MTF and one for production.

Q: How do I convert the SHA-256 to Base64?
A: Play Console shows SHA-256 in hex (2C:87:C7:…). Remove the colons and convert:

echo "2C87C73E9F758471..." | xxd -r -p | base64

For a local keystore:

keytool -exportcert -alias <alias> -keystore <keystore> | openssl dgst -sha256 -binary | base64

Q: Google Play upgraded my app signing key. Do I need to do anything?
A: Yes. Even after Play Console shows the new key as "in use", Google keeps delivering installs signed with the previous key until it migrates your install base, and some devices can present either key. Register both the old and new certificates. If you register only one, attestation fails with DeviceAttestationFailed (ATT006), either now or without warning when Google migrates.

Q: How do I check which certificate my installed app presents?
A: Pull the APK from the device and run:

adb shell pm path <package>
adb pull <path> app.apk
apksigner verify --print-certs app.apk

Compare the SHA-256 against what you registered at onboarding.

Requirements

Q: Which devices and Android versions are supported?
A: Android 11 or later, on a standard retail device with NFC, GPS and Google Play services, that passes Google Play Integrity. That means no root, no custom ROM, no emulator, and developer options turned off for production testing. Devices without Google Mobile Services (non-GMS / AOSP builds) are not supported.

Q: Does the device need GPS?
A: Yes. Tap to Pay is geofenced, so devices without GPS aren't supported. The app also needs location permission granted and location services turned on.

Q: Are foldables and tablets supported?
A: NMI hasn't tested foldables, but any device with NFC, GPS and Google Play services should work.

Q: Which countries are supported?
A: The merchant account and the physical device must be in the same supported country, and the account's currency must match. Supported for development: United States, United Kingdom, all EEA countries, Canada, China, Indonesia, Brazil, South Africa, India, Vietnam, the Philippines, Mexico, Argentina, and Israel. Production is currently available in the United States, United Kingdom, and EEA countries only. A device in another country fails regardless of configuration (for example, a device in Ukraine testing a US merchant).

Q: Which processors support Tap to Pay on Android?
A: TSYS, First Data, and Shift4. If Tap to Pay doesn't appear in Value-Added Services, the most common reason is an unsupported processor.

Q: Which cards and wallets are supported?
A: Visa and Mastercard today; Amex and Discover are rolling out. Physical contactless cards and Google Pay both work.

SDK setup

Q: What is the Application Identifier?
A: You choose the Application Identifier yourself; NMI does not issue it. It is a single word or acronym using only A–Z and 0–9, for example your company or app name. Use the same value on every platform. It can't be changed once it's registered.

Q: Do I need to reconnect before every transaction?
A: No. After a successful connectAndConfigure(), the app stays ready, including while backgrounded or when the screen locks, until something on the account changes (processor, currency, or terminal configuration). If your app re-authenticates before every transaction, review your integration flow.

Troubleshooting

Q: I don't see Tap to Pay in Value-Added Services.
A: Check these in order:

1. The service is set to Active, not Offered (Partner Portal → merchant → Value-Added Services → Update Services).
2. The account is on a supported processor.
3. If a reseller or ISO bills the account, ask them to enable it; NMI support can't.
4. The merchant's country is supported.

Q: What does this error mean?

Q: Can I test from outside the merchant's country?
A: No. The device's physical location must match the merchant account's country.

Q: What should I send to support?
A: The SDK log (how to extract it), plus:

• Gateway ID
• Package name and Application Identifier
• SDK and Cloud Commerce AAR versions
• Environment
• How the app was installed (Play track or sideload)
• The SHA-256 you registered
• Device model and Android version
• Device country
• Timestamp of the failure, in UTC

Transactions, Refunds & Reporting

Q: How do I refund a Tap to Pay transaction?
A: The same way as any gateway transaction: through the Virtual Terminal or your integration's refund call, referencing the original transaction ID. If the transaction isn't in your transaction history, it didn't complete.

Q: Where do Tap to Pay transactions appear?
A: In standard Merchant Portal and Virtual Terminal reporting. No separate reporting setup is needed.

Q: Is surcharging supported?
A: It depends on your processor and account configuration. Check with your NMI contact, because surcharging rules vary by card network and region.

Getting Help

• Account setup and Value-Added Services: your NMI account representative or merchant service provider.
• App onboarding: [email protected]. If you haven't heard back within 2–3 weeks, reply on your original thread with your submission date rather than starting a new one, which restarts the queue.
• SDK integration: submit a request, including the details listed under "What should I send to support?"