Tap to Pay on iPhone — FAQ

Getting Started

Q: What is Tap to Pay on iPhone?
A: Tap to Pay lets merchants accept contactless cards and digital wallets (Apple Pay, Google Pay) on a supported iPhone 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 the App Store.
3. Open the app and enter the NMI partner code: CC_8bFEes1a
4. Log in with the merchant's NMI Merchant Portal credentials.
5. Accept Apple's Tap to Pay on iPhone Terms & Conditions when prompted, and sign in with an active Apple Account.

Option 2: Tap to Pay SDK

Before you write any code, complete these steps:

1. Apple entitlement: request the Tap to Pay on iPhone entitlement for your App ID in the Apple Developer portal. Apple grants a Development entitlement first. Start early, because Apple's approval can take time.
2. NMI account: set Tap to Pay to Active on a sandbox account, or on a live gateway in Test Mode (see "Which NMI account should I test with?").
3. Application Identifier: choose one (see "What is the Application Identifier?").

Q: Do I need to onboard my iOS app with NMI?
A: No. Unlike Android, iOS apps don't need NMI app onboarding. You don't need to email [email protected]. Apple's entitlement is the only app-level approval.

Then follow the iOS SDK integration guide.

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). Never point the SDK's Test environment at a live gateway that isn't in Test Mode; doing so returns AccessDenied.

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.

Apple Account and entitlements

Q: What's the difference between the Development and Publishing entitlements?
A: The Development entitlement only works in the Test environment. To connect in Live, you need the Publishing entitlement. To get it, complete Apple's Tap to Pay on iPhone publishing checklist under your Development entitlement, then submit your request to Apple. You can check which one you have in the Apple Developer portal: an entitlement that lists only Development under Provisioning Support will fail in Live with AttestationFailed.

Q: Which Apple Account should my test device use?
A:

• Testing: create a Sandbox tester in App Store Connect and sign it in as the device's main Apple Account (Settings → [your name]). Adding it only under Settings → Developer is not enough.
• Production: use a normal Apple Account.
• Use a dedicated email for the sandbox tester. The email must not already be a normal Apple Account. Plus-addressing works, for example [email protected]. If a sandbox tester and a normal account share one email, Apple treats the device as a sandbox account, and every Live connection fails. NMI can't clear this state; only Apple can.

Q: A device used for development now fails in Live with InvalidAppleAccount. Why?
A: The device still carries a sandbox account state. Sign out of the Sandbox Apple Account (Settings → Developer, or Settings → App Store, depending on iOS version), confirm a normal Apple Account is signed in, then relaunch the app. If the sandbox and normal accounts share an email, sign in with a different normal Apple Account instead.

Q: When are Apple's Terms & Conditions shown?
A: The first time connectAndConfigure() runs for the Apple Account signed in on that device. ChipDNA obtains and manages the Apple reader token for you. You do not call Apple's PaymentCardReader APIs directly.

Q: Can I relink the merchant on a staff member's device that uses a different Apple Account?
A: ChipDNA does not currently expose Apple's relinkAccount API. Before connecting, make sure each staff device is signed in to a normal Apple Account that has never been used as a sandbox tester.

SDK setup

Q: Which Xcode settings does the SDK need?
A:

• Other C Flags: -DSQLITE_HAS_CODEC
• Other Linker Flags: -ObjC -lz
• Linked libraries: include CoreData.framework; remove libsqlite3.dylib / libsqlite3.0.dylib if present. The SDK bundles its own SQLCipher.
• Capabilities: Tap to Pay on iPhone entitlement on the provisioning profile; bundle ID matches your App ID.

Q: initialize() returns IncorrectPassword. What's wrong?
A: The SDK's local database is encrypted and needs a non-blank CCParamPassword. Use the same password on every initialize() call. If the error persists, check the build flags above. To reset the database, call initialize() with CCParamDestroy = TRUE, then dispose(), then initialize() again with a non-blank password.

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.

Requirements

Q: Which devices and iOS versions are supported?
A: An iPhone that supports Tap to Pay on iPhone, running iOS 18.5 or later. Tap to Pay is included only in the Full variant of the iOS SDK, which requires iOS 18.5. The Lite variant supports iOS 17.4 and later but doesn't include Tap to Pay. iPads are not supported. Apple stops supporting each iOS version one year after release, followed by a grace period of up to five months, so keep test and merchant devices up to date.

Q: Which countries are supported?
A: Tap to Pay is geofenced: the merchant account and the physical device must be in the same supported country, and the account's currency must match. Production transactions are currently available in the United States, United Kingdom, and EEA countries. If you test from another country, transactions fail regardless of configuration.

Q: Which processors support Tap to Pay on iPhone?
A: TSYS and First Data. 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, Apple Pay, and Google Pay all work.

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: What should I send to support?
A: The SDK log (how to extract it), plus:

• Gateway ID
• Bundle ID and Application Identifier
• SDK version
• CCParamEnvironment
• Entitlement type (Development or Publishing)
• iPhone model and iOS version
• 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.
• SDK integration: submit a request, including the details listed under "What should I send to support?"
• Apple entitlements and Apple Accounts: Apple Developer Support.