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 |
|---|---|
.accountLinkingRequiresiCloudSignIn | Sign in to iCloud on the device, then retry. |
| 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. |
.accountAlreadyLinked when linking | Not a problem; treat as success. |
| Link status looks stale after changes elsewhere | clearLinkStatus() then isAccountLinked(), or forceRefreshLinkStatus(). |
| 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). |
.notConfigured | One of the configuration fields is missing or empty, including merchantMid, which must never be empty. |
| Symptom | Fix |
|---|---|
.backgroundRequestNotAllowed | The call ran while the app was backgrounded. Gate reader work on the foreground state, and re-prepare when the app returns to the foreground. |
| 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.