This page covers symptom-driven fixes, Apple-side gotchas, and support contacts. For the full TapToPayError enumeration (every case, when it is thrown, how to catch it), see the Error reference.
readerPreparationFailed(String?) carries the underlying reason. The common Apple configuration codes:
| Code in message | Meaning | Fix |
|---|---|---|
| 2011 | Reader configuration (terminal profile) is invalid for this merchant/device. | Contact Finix Support with your merchant ID, Device ID, and reader identifier. |
| 2012 | Token validation failed. | Verify credentials, environment, and Device ID belong together; call refreshConfiguration(), then prepareReader() again. |
| 2013 | Merchant not authorized for Tap to Pay on iPhone. | Confirm with Finix that the merchant is enabled for Tap to Pay on iPhone in this environment. |
Also check: the app is in the foreground, the entitlement is present in the built app, the device is online, and the iPhone has a passcode set (Tap to Pay on iPhone requires one).
| Symptom | Fix |
|---|---|
| Linking or reader preparation fails on an iPhone without a passcode | Tap to Pay on iPhone requires a device passcode. Have the merchant set one in Settings → Face ID & Passcode, then retry. |
Production linking fails with accountLinkingFailed after working in Sandbox | Check whether Developer Mode is enabled on the device (Settings → Privacy & Security → Developer Mode). Developer Mode must be off for production Tap to Pay linking — Apple's production service cannot retrieve the device identity certificate when it is enabled. Disable Developer Mode, restart the device, then retry linking. Developer Mode must be on when running Sandbox builds directly from Xcode. |
| Link status looks stale after changes elsewhere | clearLinkStatus() then isAccountLinked(), or forceRefreshLinkStatus(). |
Production linking fails with accountLinkingFailed | If account linking works in sandbox but fails in production (TestFlight or App Store), check whether Developer Mode is enabled on the device (Settings → Privacy & Security → Developer Mode). Developer Mode must be off for production Tap to Pay linking. Apple's production service cannot retrieve the device identity certificate when it is enabled. Disable Developer Mode and restart the device, then retry linking. Note: Developer Mode must be on when running sandbox builds directly from Xcode. |
| Need to unlink for testing | There is no unlink API. Deleting and reinstalling the app usually resets to unlinked, but the system-level link can survive a reinstall. Check with forceRefreshLinkStatus() and rely only on a true result, because false can also mean the check failed or the device isn't provisioned yet. For a guaranteed unlinked state, use a device and Apple Account pair that has never linked. |
| Symptom | Fix |
|---|---|
Token or transaction failures mentioning the Device is not enabled or not activated | The Finix Device was never activated, or the cached Device ID is stale. Verify enabled: true via GET /devices/{device_id}; if not recoverable, discard the cached ID and re-provision. |
Authentication errors (networkAuthenticationError, tokenFetchFailed) | Credentials, Merchant, and Device must all belong to the same environment (.sandbox vs .production). This is the single most common root cause for both errors. |
| Symptom | Fix |
|---|---|
| First tap after idle is slow | The reader session went cold. Re-prepare after every transaction and on foreground (Prepare the reader). |
| UI shows a previous transaction's outcome | You subscribed to transactionEvents after a prior terminal event, and the publisher replayed the latest event. Subscribe before starting and ignore terminal events that precede your transaction. |
| Tap sheet never appears on a supported iPhone | Confirm the entitlement is in the app signature and you are not running an iOS beta. Tap to Pay on iPhone does not work on beta releases. |
Collect these values so Finix can trace the exact transaction:
traceIdandtransferIdfrom the result (or the thrown error's message).transactionIdentifierandreaderIdentifier.- The merchant ID, environment, timestamp, and what the Buyer and merchant saw.
- Finix Support: support@finix.com for merchant enablement, Device issues, and transaction investigations (include the details from Before you contact support).
- SDK issues: GitHub Issues on the SDK repository for bugs and integration questions.
- Apple entitlement process: ttpoientitlements@apple.com, including your case ID.
- Apple documentation: Tap to Pay on iPhone · Setting up the entitlement · ProximityReader.