{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-ios/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Error Reference | iOS Tap to Pay on iPhone SDK Reference","description":"Every TapToPayError case the Finix Tap to Pay on iPhone SDK can throw, grouped by where it occurs, with guidance on how to handle each one.","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":"error-reference","__idx":0},"children":["Error reference"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every error the SDK throws, and every error delivered in a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".failure"]}," event, is a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TapToPayError"]},". The enum is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Equatable"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Sendable"]}," and conforms to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["LocalizedError"]},": ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errorDescription"]}," provides an English description suitable for logs."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Match the cases you can act on and use a fallback for the rest:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"swift","header":{"controls":{"copy":{}}},"source":"do {\n    let result = try await tapToPay.startTransaction(amount: 1250, currency: \"USD\")\n    handleApproved(result)\n} catch let error as TapToPayError {\n    switch error {\n    case .accountNotLinked:\n        presentLinkFlow()\n    case .readerPreparationFailed(let details):\n        retryAfterPreparing(details)\n    case .transactionCancelled:\n        returnToCheckout()\n    case .deviceBanned(let until):\n        showDeviceBlocked(until: until)\n    default:\n        showError(error.errorDescription ?? \"Something went wrong.\")\n    }\n} catch {\n    showError(error.localizedDescription)\n}\n","lang":"swift"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every case, grouped by where it occurs:"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"setup-and-device-support","__idx":1},"children":["Setup and device support"]},{"$$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":"Error"},"children":["Error"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Thrown when"},"children":["Thrown when"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"How to handle"},"children":["How to handle"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["notSupported"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Tap to Pay on iPhone is not supported on this device (requires iPhone XS or later)."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Hide Tap to Pay on iPhone entry points. Gate your UI on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FinixTapToPay.isSupported()"]}," so users never reach this error."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["modelNotSupported"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Apple reports the specific device model as unsupported."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Same as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["notSupported"]},"; offer another payment method."]}]},{"$$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":["The SDK is missing valid configuration: credentials, merchant info, or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Device"]}," ID."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Verify all ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TapToPayConfiguration"]}," fields are present and non-empty, and that the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Device"]}," is activated."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"account-linking","__idx":2},"children":["Account linking"]},{"$$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":"Error"},"children":["Error"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Thrown when"},"children":["Thrown when"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"How to handle"},"children":["How to handle"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["accountNotLinked"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An operation requires a linked Apple Account and none is linked."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Run your ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/ios/tap-to-pay/account-linking"},"children":["link flow"]},", then retry."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["accountAlreadyLinked"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["linkAccount()"]}," was called but the merchant already accepted the Terms and Conditions."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Treat as success and continue. Don't surface it as a failure."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["accountDeactivated"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The linked Apple Account has been deactivated for the merchant."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Direct the merchant to re-link; if it persists, contact Finix Support."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["accountLinkingCancelled"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The merchant dismissed Apple's Terms and Conditions sheet."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Return to your enablement screen and let them retry."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["accountLinkingCheckFailed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The system could not check the merchant's link status."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Retry with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["forceRefreshLinkStatus()"]},"; check connectivity."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["accountLinkingFailed(String?)"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Linking failed. The message includes details when available."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Show a retry option and log the message. Verify iCloud sign-in and connectivity."]}]},{"$$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":["The device is not signed in to iCloud."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Prompt the merchant to sign in to iCloud in Settings, then retry."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"reader-preparation","__idx":3},"children":["Reader preparation"]},{"$$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":"Error"},"children":["Error"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Thrown when"},"children":["Thrown when"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"How to handle"},"children":["How to handle"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["readerPreparationFailed(String?)"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The reader could not be prepared. The message includes the underlying reason, including Apple codes 2011, 2012, and 2013."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/ios/tap-to-pay/support"},"children":["Troubleshooting and support"]}," for the fix for each code. Resolve the cause, then call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["prepareReader()"]}," again."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["emptyReaderToken"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Finix returned an empty reader token."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Usually transient. Retry, and if it persists, verify the configuration and contact Finix Support."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invalidReaderToken(String?)"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The reader token was rejected as invalid."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Verify the credentials, environment, and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Device"]}," ID all belong to the same environment. Call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["refreshConfiguration()"]}," and prepare again."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"transactions","__idx":4},"children":["Transactions"]},{"$$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":"Error"},"children":["Error"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Thrown when"},"children":["Thrown when"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"How to handle"},"children":["How to handle"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionCancelled"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The Buyer, the merchant, or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cancelTransaction()"]}," cancelled the payment."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Return to checkout. No funds moved."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionFailed(String)"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The payment was declined or failed in processing. The message gives the reason."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Show your declined screen and offer another payment method. Log the message."]}]},{"$$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":["A reader operation was attempted while the app was in the background."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Only link, prepare, and transact while the app is in the foreground. Re-issue the call after the app returns to the foreground."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["deviceBanned(Date?)"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Apple has blocked this device from Tap to Pay on iPhone, optionally until the given date."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Show the date if present. Direct the merchant to another payment method and contact Finix Support."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"merchant-network-and-tokens","__idx":5},"children":["Merchant, network, and tokens"]},{"$$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":"Error"},"children":["Error"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Thrown when"},"children":["Thrown when"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"How to handle"},"children":["How to handle"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invalidMerchant"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The merchant is invalid or unknown to Finix."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Verify ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchantId"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchantMid"]}," belong to the configured environment."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchantBlocked"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The merchant is blocked from using Tap to Pay on iPhone."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Contact Finix Support."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tokenFetchFailed(String)"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Authenticating with Finix to obtain a Tap to Pay on iPhone token failed."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Verify credentials, connectivity, and that the Device is activated, then retry."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["networkAuthenticationError"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A network-level authentication error occurred talking to Finix."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Verify API credentials match the configured environment."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unknown(String)"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An unexpected error. The message contains whatever detail is available."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Log the message with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["traceId"]}," if you have one, and contact Finix Support if reproducible."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Next:"]}," ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/ios/tap-to-pay/testing"},"children":["Test your integration"]},"."]}]},"headings":[{"value":"Error reference","id":"error-reference","depth":1},{"value":"Setup and device support","id":"setup-and-device-support","depth":2},{"value":"Account linking","id":"account-linking","depth":2},{"value":"Reader preparation","id":"reader-preparation","depth":2},{"value":"Transactions","id":"transactions","depth":2},{"value":"Merchant, network, and tokens","id":"merchant-network-and-tokens","depth":2}],"frontmatter":{"seo":{"title":"Error Reference | iOS Tap to Pay on iPhone SDK Reference","description":"Every TapToPayError case the Finix Tap to Pay on iPhone SDK can throw, grouped by where it occurs, with guidance on how to handle each one."}},"lastModified":"2026-08-11T19:49:07.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/ios/tap-to-pay/errors","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}