{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-ios/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Troubleshooting & Support | iOS Tap to Pay on iPhone SDK Reference","description":"Fixes for common Finix Tap to Pay on iPhone SDK problems, what to collect before contacting support, and where to get help.","siteUrl":"https://docs.finix.com/","llmstxt":{"hide":false,"sections":[{"title":"Getting Started","includeFiles":["guides/getting-started/**/*.md"],"excludeFiles":[]},{"title":"Online Payments","includeFiles":["guides/online-payments/**/*.md"],"excludeFiles":["guides/online-payments/payment-features/fsa-hsa-non-healthcare-mcc.md"]},{"title":"In-Person Payments","includeFiles":["guides/in-person-payments/**/*.md"],"excludeFiles":[]},{"title":"Subscriptions","includeFiles":["guides/subscriptions/**/*.md"],"excludeFiles":[]},{"title":"After the Payment","includeFiles":["guides/after-the-payment/**/*.md"],"excludeFiles":[]},{"title":"Managing Operations","includeFiles":["guides/managing-operations/**/*.md"],"excludeFiles":[]},{"title":"Platform Payments","includeFiles":["guides/platform-payments/**/*.md"],"excludeFiles":[]},{"title":"Payouts","includeFiles":["guides/payouts/**/*.md"],"excludeFiles":[]},{"title":"Low-Code / No-Code","includeFiles":["low-code-no-code/**/*.md"],"excludeFiles":[]},{"title":"Developers","includeFiles":["additional-resources/developers/**/*.md"],"excludeFiles":[]},{"title":"Plugins","includeFiles":["additional-resources/plugins/**/*.md"],"excludeFiles":[]},{"title":"Industry Considerations","includeFiles":["guides/industry-considerations/**/*.md"],"excludeFiles":[]},{"title":"Regional Considerations","includeFiles":["guides/regional-considerations/**/*.md"],"excludeFiles":[]},{"title":"Release Notes","includeFiles":["release-notes/**/*.md"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"troubleshooting-and-support","__idx":0},"children":["Troubleshooting and support"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"reader-preparation-failures","__idx":1},"children":["Reader preparation failures"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["readerPreparationFailed(String?)"]}," carries the underlying reason. The common Apple configuration codes:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Code in message"},"children":["Code in message"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Fix"},"children":["Fix"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["2011"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Reader configuration (terminal profile) is invalid for this merchant/device."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Contact Finix Support with your merchant ID, Device ID, and reader identifier."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["2012"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Token validation failed."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Verify credentials, environment, and Device ID belong together; call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["refreshConfiguration()"]},", then ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["prepareReader()"]}," again."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["2013"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Merchant not authorized for Tap to Pay on iPhone."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Confirm with Finix that the merchant is enabled for Tap to Pay on iPhone in this environment."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Also check: the app is in the foreground, the entitlement is present in the built app, and the device is online."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"linking-problems","__idx":2},"children":["Linking problems"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Symptom"},"children":["Symptom"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Fix"},"children":["Fix"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".accountLinkingRequiresiCloudSignIn"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Sign in to iCloud on the device, then retry."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".accountAlreadyLinked"]}," when linking"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Not a problem; treat as success."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Link status looks stale after changes elsewhere"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["clearLinkStatus()"]}," then ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["isAccountLinked()"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["forceRefreshLinkStatus()"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Need to unlink for testing"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["forceRefreshLinkStatus()"]}," and rely only on a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}," result, because ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"device-and-configuration-problems","__idx":3},"children":["Device and configuration problems"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Symptom"},"children":["Symptom"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Fix"},"children":["Fix"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Token or transaction failures mentioning the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Device"]}," is not enabled or not activated"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The Finix ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Device"]}," was never activated, or the cached Device ID is stale. Verify ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["enabled: true"]}," via ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /devices/{device_id}"]},"; if not recoverable, discard the cached ID and ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/ios/tap-to-pay/device-setup"},"children":["re-provision"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Authentication errors (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["networkAuthenticationError"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tokenFetchFailed"]},")"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Credentials, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Merchant"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Device"]}," must all belong to the same environment (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".sandbox"]}," vs ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".production"]},")."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".notConfigured"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["One of the configuration fields is missing or empty, including ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchantMid"]},", which must never be empty."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"transaction-problems","__idx":4},"children":["Transaction problems"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Symptom"},"children":["Symptom"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Fix"},"children":["Fix"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".backgroundRequestNotAllowed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["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."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["First tap after idle is slow"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The reader session went cold. Re-prepare after every transaction and on foreground (",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/ios/tap-to-pay/transactions#prepare-the-reader"},"children":["Prepare the reader"]},")."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["UI shows a previous transaction's outcome"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["You subscribed to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionEvents"]}," after a prior terminal event, and the publisher replayed the latest event. Subscribe before starting and ignore terminal events that precede your transaction."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Tap sheet never appears on a supported iPhone"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["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."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"before-you-contact-support","__idx":5},"children":["Before you contact support"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Collect these values so Finix can trace the exact transaction:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["traceId"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transferId"]}," from the result (or the thrown error's message)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionIdentifier"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["readerIdentifier"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The merchant ID, environment, timestamp, and what the Buyer and merchant saw."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"get-help","__idx":6},"children":["Get help"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Finix Support"]},": ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"mailto:support@finix.com"},"children":["support@finix.com"]}," for merchant enablement, Device issues, and transaction investigations (include the details from ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"#before-you-contact-support"},"children":["Before you contact support"]},")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["SDK issues"]},": ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://github.com/finix-payments/finix-taptopay-ios-sdk/issues"},"children":["GitHub Issues"]}," on the SDK repository for bugs and integration questions."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Apple entitlement process"]},": ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"mailto:ttpoientitlements@apple.com"},"children":["ttpoientitlements@apple.com"]},", including your case ID."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Apple documentation"]},": ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://developer.apple.com/tap-to-pay/"},"children":["Tap to Pay on iPhone"]}," · ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://developer.apple.com/documentation/proximityreader/setting-up-the-entitlement-for-tap-to-pay-on-iphone"},"children":["Setting up the entitlement"]}," · ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://developer.apple.com/documentation/proximityreader"},"children":["ProximityReader"]},"."]}]}]},"headings":[{"value":"Troubleshooting and support","id":"troubleshooting-and-support","depth":1},{"value":"Reader preparation failures","id":"reader-preparation-failures","depth":2},{"value":"Linking problems","id":"linking-problems","depth":2},{"value":"Device and configuration problems","id":"device-and-configuration-problems","depth":2},{"value":"Transaction problems","id":"transaction-problems","depth":2},{"value":"Before you contact support","id":"before-you-contact-support","depth":2},{"value":"Get help","id":"get-help","depth":2}],"frontmatter":{"seo":{"title":"Troubleshooting & Support | iOS Tap to Pay on iPhone SDK Reference","description":"Fixes for common Finix Tap to Pay on iPhone SDK problems, what to collect before contacting support, and where to get help."}},"lastModified":"2026-08-11T19:49:07.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/ios/tap-to-pay/support","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}