Frequently Asked Questions

Getting Started

Q: What is Tap to Pay?
A: Tap to Pay lets you accept contactless card and digital wallet payments (Visa, Mastercard, and others) directly on a compatible phone or tablet — no separate card reader required. NMI supports this through two paths: the ready-made Cloud Commerce app, or a Tap to Pay SDK you can build into your own app.

Q: What's the difference between the Cloud Commerce app and the SDK?
A: Cloud Commerce is a free, pre-built app (Mastercard's app) you download from the App Store or Google Play — good if you want to start accepting payments quickly with no development work. The SDK is for partners who want Tap to Pay embedded directly inside their own custom app.

Option 1: Cloud Commerce App (fastest way to start)

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.
Download Cloud Commerce from the Google Play Store or Apple App Store.
Disable Bluetooth and unplug any peripherals from the device before setup.
Open the app and enter the NMI partner code: CC_8bFEes1a
Log in with the merchant's existing NMI Merchant Portal credentials.

That's it — no additional hardware or onboarding is required for this option.

Option 2: Tap to Pay SDK (for custom apps)

If you're building Tap to Pay into your own app, you'll need to complete a one-time app onboarding process before it will work, even in a sandbox/test environment. This is separate from simply enabling the Tap to Pay service on the merchant account.

Follow the SDK integration guide for your platform (Android or iOS).
Submit your app's package name, keystore hash (SHA-256, Base64-encoded), and Play Integrity response encryption keys to [email protected].
Tell the onboarding team every country you intend to test and launch in — this can't be added after the fact without a follow-up request.

Onboarding typically takes 2–3 weeks. Submit it as early as possible in your development timeline so it isn't a late-stage blocker.

Device, Country & Processor Requirements

Q: What devices and OS versions are supported?
A: Android 11+ or iOS 17.4+, with NFC enabled on the device. For Android, the device must pass Google Play Integrity checks (standard, non-rooted retail devices). For iPhone, the device must support "Tap to Pay on iPhone" and the merchant must sign in with an active Apple ID during setup.

Q: Which countries is Tap to Pay available in for developers?
A: Tap to Pay uses geofencing as a fraud-prevention measure, so it's only available in specific countries, and both the merchant account and the physical device must be located in the same supported country. Supported countries include the United States, United Kingdom, all EEA countries, Canada, China, Indonesia, Brazil, South Africa, India, Vietnam, the Philippines, Mexico, Argentina, and Israel. If you're testing from a country not on this list, transactions will fail regardless of your app configuration. Production transactions are only available in the United States, United Kingdom, and EEA countries today.

Q: Why does my transaction fail even though everything looks configured correctly?
A: The most common cause is a mismatch between the merchant account's configured country and the physical location of the test device — for example, testing from India on a merchant account configured for the US. Both must match, including the account's currency setting.

Q: Which processors support Tap to Pay?
A: Tap to Pay requires an active, supported processor on the merchant account (for example, TSYS). If you don't see the Tap to Pay option in Value-Added Services, the most common reason is that the account isn't yet on a compatible processor — check with your NMI contact to confirm compatibility before troubleshooting further.

Q: Which cards and wallets are supported?
A: Visa and Mastercard are supported today; Amex and Discover support is being rolled out. Both physical contactless cards and mobile wallets (Apple Pay, Google Pay) can be used, depending on the platform.

Troubleshooting Common Setup Issues

Q: I don't see Tap to Pay as an option in Value-Added Services — why not?
A: This is almost always one of: (1) the account isn't on a supported processor yet, (2) the account is with a reseller/ISO rather than NMI directly, in which case Tap to Pay needs to be enabled by them rather than NMI support, or (3) the merchant's country isn't currently supported. Contact your merchant service provider first if you're not billed directly by NMI.

Q: My app build shows a "General Error" or "App Tampered" error — what does that mean?
A: This almost always relates to how the app was signed. Google Play re-signs apps with its own certificate when you publish (even to Internal Testing), so the certificate fingerprint your app sends can end up not matching what was registered during onboarding. Two things to check: (1) confirm you're using the Play Store App Signing Key fingerprint — not your local upload key — in your onboarding submission and in your app's configuration, and (2) if testing locally, sideload the APK directly rather than installing through Play, since local and Play-distributed builds are signed differently.

Q: I'm getting a "Registration Required" or device attestation error — what should I check first?
A: Confirm the app has completed the full onboarding process (package name, keystore hash, Play Integrity keys, and target countries all submitted and confirmed by [email protected]) — this is the single most common cause. If onboarding is confirmed complete, next check that the test device's location and the merchant account's country/currency configuration match, and that the device is running a supported OS version with NFC enabled.

Q: Can I test Tap to Pay in a sandbox account?
A: Yes, but the sandbox account still needs Tap to Pay onboarding completed (for SDK integrations) or the merchant needs to be a registered partner with Tap to Pay enabled (for Cloud Commerce). A generic sandbox account with no onboarding won't show the option.

Q: How long does app onboarding usually take, and what can I do if it's running long?
A: Plan for 2–3 weeks from submission. If you haven't heard back within that window, follow up with [email protected] referencing your original submission date rather than opening a new request, since a new request restarts the queue.

Transactions, Refunds & Reporting

Q: How do I refund a Tap to Pay transaction?
A: Refunds are processed the same way as other transactions on the gateway — through the Virtual Terminal or your integration's refund call, referencing the original transaction ID. If a Tap to Pay transaction doesn't appear in your transaction history at all, that usually indicates the transaction didn't complete successfully rather than a refund-specific issue.

Q: Can Tap to Pay support surcharging?
A: Surcharging support depends on your processor and account configuration. Check with your NMI contact to confirm whether surcharging is enabled and compliant for your specific setup, since surcharging rules vary by card network and region.

Q: Does Tap to Pay support its own reporting, or does it need to be used through the Virtual Terminal?
A: Tap to Pay transactions post to the same gateway reporting as any other transaction type, so they're visible in the standard Merchant Portal / Virtual Terminal reporting — a separate reporting setup isn't required.

Q: Do I need to reconnect / re-authenticate before every transaction?
A: No. Once your app successfully completes its initial connection and configuration step, it should remain ready for transactions — including while backgrounded or when the screen locks — until something on the account changes (for example, a processor, currency, or terminal configuration update). If your app is re-authenticating before every single transaction, that's usually unnecessary and worth reviewing in your integration flow.

Getting Help

For account setup and Value-Added Services questions, contact your NMI account representative or merchant service provider.

For SDK onboarding questions, contact [email protected].

For general support, visit the NMI Help Center or submit a request: support.nmi.com/hc