Transaction Response Codes
Error Handling
The TapOnMobileSDK uses a unified error handling mechanism through the TapOnMobileError enum. All asynchronous operations return a Result type that, in case of failure, contains a specific TapOnMobileError. This section categorizes these errors, explains their causes, and provides recommended actions for integrators.
Error categories:
The TapOnMobileError enum is categorized into several cases to help identify the source of the issue:
Below can be found the specification of TapOnMobileError, which is an enum that contains all errors returned by the TapOnMobile SDK.
1. Common Errors (.common)
Generic errors that can occur across various features.
| Error case | Description | Recommended action |
|---|---|---|
| unsupported | The requested service type is not supported | Check device compatibility or terminal configuration. Hide unsupported features from the UI. |
| notAllowed | The action is not allowed in the current state. | Ensure the app flow is correct and terminal configuration (e.g., QR payment service called when APM is not enabled in the current terminal). |
| tippingNotAllowed | Tipping is disabled on this terminal configuration. | Do not prompt the user for a tip amount. |
| timeout | The operation took too long to complete. | Retry the operation or check network stability. |
| internalError | An internal error occurred within the payment service or SDK. | Retry the operation. If it persists, contact support. |
| tokenError | Error during token encryption/decryption. | Re-authenticate or restart the session. |
| invalidAmount | The provided transaction amount is invalid. | Validate input before calling the SDK. |
| invalidTransactionId | The provided transaction ID format is incorrect. | Ensure the ID matches the expected format (UUID). |
| invalidPassword | The password provided does not match the merchant portal's password for the selected refund. | Prompt the user to re-enter the correct password. |
| referenceFieldTooLong | The reference string exceeds the allowed character limit. | Truncate or validate the reference string before sending. |
| readerBusyWarning | The card reader is currently busy. | This is usually temporary. Wait a moment and retry or ignore if it's a non-blocking warning. |
| missingRequiredFilterParameter | Required filters (transactionId or reference) were missing for fetching details. | Ensure at least one unique identifier is provided. |
2. Session Errors (.session)
Errors related to user authentication and terminal registration status.
| Error case | Description | Recommended action |
|---|---|---|
| sessionError | The request failed due to missing or invalid authentication credentials. | Prompt the user to log in again. |
| invalidCredentials | The provided credentials (secure code, etc.) are incorrect. | Ask the user to verify and re-enter their credentials. |
| terminalUnregistered | The device has been manually unregistered from the merchant portal or the session is invalidated. | Restart the registration process. |
3. Backend Errors (.backend)
Issues arising from network communication or server responses.
| Error case | Description | Recommended action |
|---|---|---|
| networkError | Network connection failed or was lost. | Check internet connectivity and retry. |
| invalidRequestError | The request was malformed. | Check SDK configuration and update to the latest version. |
| invalidResponse | Received a non-HTTP or malformed response from the server. | Retry later; if persistent, contact support. |
| serverError(code, description) | The server returned an error. | Display the description to the user or handle specific codes (e.g., insufficient funds). |
| mtlsError | Indicates that the MTLS check failed | Performing a fresh re-registration. Please unregister the terminal and then complete the registration process |
4. Initialization Errors (.initialization)
Errors occurring during the SDK setup phase.
| Error case | Description | Recommended action |
|---|---|---|
| initializationNotCompleted | A method was called before initialization() completed successfully. | Ensure initialization() is called and returns success before using other SDK features. |
| initializationAlreadyCompleted | initialization() was called more than once. | Check your app logic to ensure initialization runs only once per session. |
| invalidCertificateData | The provided certificate data is invalid. | Verify the certificate parameters passed to initialization(). |
| invalidEnvironment | An invalid environment was selected. | Use a valid Environments enum value |
5. Location Errors (.location)
Issues related to device location services, which are required for transactions.
| Error case | Description | Recommended action |
|---|---|---|
| locationUnauthorized | The app does not have permission to access location. | Prompt the user to enable location permissions in iOS Settings. |
| validLocationNotFound | The device could not determine its location. | Ensure the user is in an area with GPS/Wi-Fi signal and retry. |
| countryNotPermitted | The device is in a country where the service is not permitted. | Inform the user that the service is unavailable in their current location. |
6. Local storage Errors (.local)
Issues accessing data stored on the device.
| Error case | Description | Recommended action |
|---|---|---|
| itemNotFound | A requested item (e.g., cached transaction) was not found. | Handle as a "not found" state in your UI. If error persist re-authenticate. |
| alreadyLogOut | Attempted an action requiring a session after logout. | Redirect to the login screen. |
7. Card Reader Session Errors (.cardReaderSession)
These errors typically occur during device initialization or when calling prepareDevice(). They indicate issues with the environment, merchant account linking, or device state that prevent a reading session from being established. Bellow the recommended actions provided by Apple:
| Error case | Description | Recommended action |
|---|---|---|
| accountNotLinked | Merchant has not accepted the Terms of Service with a valid Apple ID | Call prepareDevice() to prompt T&C acceptance or notify the merchant. |
| accountLinkingFailed | System failed to link the merchant using the provided Apple ID. | Advise the merchant to try again. |
| accountLinkingRequiresICloudSignIn | Merchant must be signed into iCloud to accept Terms of Service. | Advise the merchant to sign into iCloud. |
| networkAuthenticationError | Authentication error during connection to Apple servers. | Check network settings and try again. |
| networkError | General network connectivity issue. | Check network settings and try again. |
| osVersionNotSupported | Current iOS version does not support Tap to Pay on iPhone. | Advise merchant to update iOS to the latest version. |
| passcodeDisabled | Device passcode is disabled (required for secure element). | Advise merchant to enable a device passcode. |
| deviceBanned | Device is temporarily banned due to eligibility criteria failure. | Inform the merchant of the date when it will be usable again. |
| invalidMerchant | Merchant identity is invalid or unknown. | Verify merchant configuration and login again. |
| merchantBlocked | Merchant is blocked from using Tap to Pay. | Advise merchant to contact support. |
| notReady | Reader session is not ready. | Call prepareDevice() to open a new session. |
| prepareFailed | Internal failure during device preparation. | Retry the operation; if it persists, contact support. |
| serviceConnectionError | Internal system service is unavailable. | Inform the merchant that Tap to Pay is currently unavailable. |
| tokenExpired | The session token has expired. | Do login and call prepareDevice(). |
| readerMemoryFull | Reader's internal secure memory is full. | Advise merchant to remove some cards from Wallet or factory reset. |
| modelNotSupported | The iPhone model does not support Tap to Pay. | Do not offer Tap to Pay as an option on this device. |
| notAllowed | Entitlement, configuration, or app bundle issue. | Verify app entitlements and project configuration. |
| unsupported | General "Unsupported" state for the hardware/region. | Check if the region and device are supported for Tap to Pay. |
Note: The readerBusy error from PaymentCardReaderError is automatically mapped to TapOnMobileError.common(.readerBusyWarning) by the SDK.
8. Card Read Errors (.cardRead)
These errors occur during an active payment or refund process (e.g., within doPayment() or doRefund()) after the reader UI has been presented to the customer. Bellow the recommended actions provided by Apple:
| Error Case | Description | Recommended Action |
|---|---|---|
| cardNotSupported | The card is not supported by the current configuration. | Inform the user their card is not supported and suggest using a different payment method. |
| cardReadFailed | An error occurred when reading the card data. | Prompt the user to hold the card correctly and try again. If it fails, suggest using a different card. |
| invalidAmount | The request contained an invalid amount (e.g., negative). | This is an app validation issue. The app should prevent invalid amounts from being submitted. |
| invalidCurrencyCode | The request included an invalid currency code. | This is a developer configuration/validation issue that should be fixed in the app. |
| invalidPreferredAID | The preferred AID/RID specified in the configuration is invalid. | This is a developer configuration error that needs to be fixed. |
| invalidVASMerchants | The specified list of VAS (Value-Added Service) merchants is invalid. | This is a developer configuration error that needs to be fixed. |
| invalidVASRequestParameters | The specified VAS (Value-Added Service) parameters are invalid. | This is a developer configuration error that needs to be fixed. |
| noReaderSession | No reader session is available or the session isn't ready. | Do login and call prepareDevice(). |
| nfcDisabled | NFC is disabled on the device. | Prompt the user to enable NFC in their device settings. |
| passcodeDisabled | Read operations are not allowed when the device's passcode is disabled. | Prompt the user to enable the passcode in their device settings. |
| paymentCardDeclined | The transaction was declined by the card issuer. | Inform the user the payment was declined and suggest trying a different card. |
| paymentReadFailed | An internal failure prevented the payment from being read. | Ask the user to try again or use a different payment card. |
| pinCancelled | The PIN entry was cancelled by the user or system. | No action needed as this was a cancellation. Return to the previous screen. |
| pinEntryFailed | An error occurred when capturing the PIN. | Inform the user the PIN entry failed and to try the transaction again. |
| pinEntryTimeout | The PIN was not entered within the allowed time. | Inform the user that the time for PIN entry expired and to try the transaction again. |
| pinNotAllowed | PIN capture is not supported or has expired for this transaction. | Inform the user that PIN entry is not available for this payment method. |
| pinTokenInvalid | An error indicates an invalid PIN token was used. | This is a developer/backend security issue that needs to be investigated. |
| readCancelled | The read operation was cancelled by the user. | No action is needed as this was a user-initiated action. Return to the checkout screen. |
| readFromBackgroundError | The app attempted a read operation while in the background. | Ensure the user brings the app to the foreground to complete the payment. |
| readNotAllowed | The read operation isn't allowed, often due to an entitlement issue. | The app should handle this state gracefully, likely by re-initializing the payment flow. |
| readNotAllowedDuringCall | Read operations are not allowed during a phone call. | Prompt the user to end the phone call and then try the payment again. |
| readerInitializationFailed | The reader failed to initialize. | This is a critical error. Call prepareDevice() or prompt the user to restart. |
| readerNotAvailable | The reader is temporarily unavailable. | Inform the user the reader is temporarily unavailable and to try again shortly. |
| readerServiceConnectionError | The app was unable to connect to the system's reader services. | Call prepareDevice() again after 30 seconds. |
| readerServiceError | A general internal reader service error occurred. | Call prepareDevice() again after 30 seconds. |
| readerSessionAuthenticationError | An authentication error occurred while refreshing the reader session. | Call prepareDevice() again after 30 seconds. |
| readerSessionBusy | The reader is busy with another operation (e.g., two taps at once). | This is an internal app logic issue. Ensure the app handles one transaction at a time. |
| readerSessionExpired | The reader session has expired and could not be refreshed. | Do login and call prepareDevice(). |
| readerSessionNetworkError | A network error prevented the reader session from refreshing. | The app should try to call prepareDevice(). The user may need to check their internet connection. |
| readerTokenExpired | The configuration token for the reader session has expired. | Do login and call prepareDevice(). |
| storeAndForwardDeclineFailed | An offline decline request was made after the allowed time window. | This is an internal processing error for offline transactions. No specific user action. |
| storeAndForwardResultNotFound | The framework could not find the original result for an offline decline. | This is an internal processing error for offline transactions. No specific user action. |
| unknown | An unexpected error occurred. | Display a generic error message and provide a way for the user to report the issue if it persists. |
| vasReadFail | An error occurred when reading a loyalty pass. | Inform the user the loyalty pass could not be read and to try again. |
9. Unknown Error (.unknown)
Unexpected errors that do not fit other categories.
Action: Log the error details and contact support if it affects critical flows.
Annex: Transaction Response Codes
Both TransactionDetail and APMTransaction have a parameter called Response Code which returns the number corresponding to the transaction response:
- If the transaction code is 0:
- transaction response approved
- If the transaction code is one of [06, 09, 21, 58, 97, 98, 99]:
- transaction response technical error
- If the transaction code is 10:
- transaction response partial approval
- If the transaction code is 11:
- transaction response invalid transaction
- If the transaction code is 33:
- transaction response expired card
- If the transaction code is 43:
- transaction response not permitted
- If the transaction code is 55:
- transaction response incorrect pin
- If the transaction code is 56:
- transaction response invalid card
- If the transaction code is 60:
- transaction response pin required
- If the transaction code is 61:
- transaction response insufficient funds
- If the transaction code is 67:
- transaction response exceeds withdrawal amount
- If the transaction code is 77:
- transaction response pin try limit
- If the transaction code is 86:
- transaction response exceeds withdrawal frequency
- If the transaction code is 87:
- transaction response approved purchase_only
- For any other transaction code (default case):
- transaction response declined