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, and the device is online.
Linking problems
Symptom
Fix
.accountLinkingRequiresiCloudSignIn
Sign in to iCloud on the device, 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.
Device and configuration problems
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.
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.
Transaction problems
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.
Before you contact support
Collect these values so Finix can trace the exact transaction:
traceId and transferId from the result (or the thrown error's message).
transactionIdentifier and readerIdentifier.
The merchant ID, environment, timestamp, and what the Buyer and merchant saw.