# Troubleshooting and support

## Reader preparation failures

`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](/ios/tap-to-pay/device-setup). |
| 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. |


## 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](/ios/tap-to-pay/transactions#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.


## Get help

- **Finix Support**: [support@finix.com](mailto:support@finix.com) for merchant enablement, Device issues, and transaction investigations (include the details from [Before you contact support](#before-you-contact-support)).
- **SDK issues**: [GitHub Issues](https://github.com/finix-payments/finix-taptopay-ios-sdk/issues) on the SDK repository for bugs and integration questions.
- **Apple entitlement process**: [ttpoientitlements@apple.com](mailto:ttpoientitlements@apple.com), including your case ID.
- **Apple documentation**: [Tap to Pay on iPhone](https://developer.apple.com/tap-to-pay/) · [Setting up the entitlement](https://developer.apple.com/documentation/proximityreader/setting-up-the-entitlement-for-tap-to-pay-on-iphone) · [ProximityReader](https://developer.apple.com/documentation/proximityreader).