The Adyen payments platform performs regular checks to make sure that the mobile device on which the SDK is installed is secure. If an issue is found during the security attestation process, an error is shown on the mobile device. In many cases end users can resolve the issue themselves. The user needs to resolve the issue before trying to use the device again.
The following tables show the most common errors and how to handle them.
Device error messages
You need to resolve the issue before trying to use the device again. Refer to the column Internet needed to resolve to learn if your integration needs internet connectivity to resolve the error.
| Error code | Description | Internet needed to resolve | Required action |
|---|---|---|---|
| DEBUGGER_ENABLED | Transaction canceled. |  |
Disconnect the debugger and try again. |
| INVALID_NYC1_FIRMWARE_VERSION | Card reader firmware version is invalid. |  |
Update the card reader to the latest software version and try again. |
| LOCAL_TIME_TAMPERING | Transaction canceled. Unable to check the security requirements. | |
On the device, go to Settings > General > Date & Time and turn on Set automatically. |
| NON_SELF_RESOLVABLE | Transaction canceled. Unable to check the security requirements. | |
Contact our Support Team to resolve the issue. |
| NO_TOKEN | Cannot transact. | |
Connect the device to a network so that the SDK can check the security requirements. |
| OFFLINE_DATA_TAMPERING | An error occurred, offline data may have been lost. | |
Connect the device to a network so that the SDK can check the security requirements. |
| PASSCODE_NOT_ENABLED | Transaction canceled. Device passcode was removed, offline transaction data may have been lost. | |
On the device, go to Settings > Face ID & Passcode, set a passcode for this device, and try again. All offline "Store and Forward" transactions previously performed with the original passcode have been lost and cannot be recovered. You will not be able to continue making offline transactions until the error is resolved. |
| SCREEN_RECORDING | Transaction canceled. | |
Stop screen recording and try again. |
| SCREEN_CAPTURED | Transaction canceled. | |
Screen capture is not allowed. Try again. |
| SCREEN_TAMPERING | Transaction canceled. | |
Try again. Keep the app open and in full-screen mode while the transaction is in progress. |
| SCREEN_OVERLAY | Transaction canceled. | |
Keep the app open and in full-screen while the transaction is in progress. |
| SYSTEM_CHANGE | Transaction canceled. Cannot transact due to system change. | |
Connect the device to a network so that the SDK can check the security requirements. If the date/time of the device was changed, you must change it back to continue transacting. If the device was restarted, it must go online for the SDK to check security requirements. |
| TOKEN_EXPIRED_S&F | Offline transaction window has expired. | |
Connect the device to a network so that the SDK can check the security requirements. |
AdyenPOSError cases
AdyenPOSError is a public Swift enum that can be thrown when you call SDK methods, for example PaymentService.performTransaction(), warmUp(), performDiagnosis(), or a firmware update method. You handle these errors in your own code. They can occur with any iOS Mobile SDK integration, including Tap to Pay on iPhone and card reader (NYC1) integrations.
The Localized message column shows the English reference text. The actual message follows the same language hierarchy as the rest of the transaction flow: it can be shown in the shopper's card language, your configured primary or secondary language, or the device's language.
AdyenPOSError using print(error) or error.localizedDescription, you get an unreadable value such as AdyenPOSError 6. Use String(describing: error) to get the localized message shown in the tables below.Transaction errors
Errors related to starting or processing a payment transaction.
| Error case | Localized message | Required action |
|---|---|---|
malformedTransactionRequest |
Unable to parse Terminal API request: {error}. | Check that your Terminal API payment request is structured correctly. |
transactionInProgress |
Unable to proceed because there is a transaction in progress. | Wait for the current transaction to finish before you start a new one. |
Device and connection errors
Errors related to the mobile device's state or its connection to a card reader.
| Error case | Localized message | Required action |
|---|---|---|
deviceConnectionFailure |
Unable to connect to the reader with serial number {sn}: {reason}. | Check that the card reader is turned on and within range, then try to connect again. |
noPairedReaders |
No previously paired readers found. | Pair a card reader with the SDK before you try to use it. |
deviceLocked |
Device is locked. Please unlock the device and try again. | Unlock the device before you perform SDK operations. |
passcodeDisabled |
Device passcode was removed, offline data may have been lost. Please set a passcode and try again. | Set a device passcode. Offline "Store and Forward" data saved with the previous passcode may be lost. |
unableToFetchCardReaderBatteryInfo |
Unable to retrieve battery information from the card reader. | Check that the card reader is connected, then try again. |
Tap to Pay errors
Errors specific to Tap to Pay on iPhone.
| Error case | Localized message | Required action |
|---|---|---|
tapToPayNotSupported |
Tap to Pay is not supported on this device due to device model and/or iOS version. | Use a device and iOS version that meet the Tap to Pay on iPhone requirements. |
tapToPayNotAllowed |
Tap to Pay is not allowed. Most likely the app is missing an entitlement to use it. | Request the Tap to Pay on iPhone entitlement from Apple for your app. |
tapToPayPaymentInterfaceFailure |
Unable to retrieve Tap to Pay payment interface: {reason} | Try again. If the issue persists, contact our Support Team. |
Configuration and lifecycle errors
Errors related to SDK setup and your app's lifecycle, for example warming up or backgrounding.
| Error case | Localized message | Required action |
|---|---|---|
unableToObtainInstallationId |
Unable to generate an application identifier. | Check that your device has a network connection and a passcode set, then try again. If the issue persists, reinstall the app or contact our Support Team. |
backgroundWarmupNotAllowed |
Unable to warm up if the application is in the background. | Call warmUp() only while your app is in the foreground. |
invalidSuccessScreenTimeout |
The value for successScreenTimeout is not within the allowed range. | Set successScreenTimeout to a value between 0.5 and 4 seconds (default is 4 seconds). |
Rate limiting
Errors returned when your integration sends too many requests in a short time.
| Error case | Localized message | Required action |
|---|---|---|
tooManyRequests |
Too many session-related requests. Please wait before retrying. | Wait before you retry, and add backoff logic to your integration. Check your session establishment flow for requests sent too frequently. |
Education errors
Errors related to showing education screens that instruct end users how to use Tap to Pay on iPhone.
| Error case | Localized message | Required action |
|---|---|---|
educationNotSupported |
Education for the provided payment interface/action is not supported. | Only call presentEducationForTapToPay(for:) for a supported payment interface and action. |
educationFailedToDisplay |
Failed to display education for the provided payment interface/action. | Try again. If the issue persists, contact our Support Team. |
Firmware errors
Firmware errors are returned as firmwareError(reason:). The reason value tells you exactly what went wrong:
| Reason | Localized message | Required action |
|---|---|---|
generalError |
A general firmware error occurred. | Try the firmware update again. |
noConnectedDevices |
There are no connected devices. | Connect the card reader before you start a firmware update. |
noConnectedDock |
There are no connected docks. | Dock the card reader before you start a firmware update. |
firmwareDelegateNotSet |
The delegate is not set correctly. | Set the firmware delegate in your integration. |
noUpdateAvailable |
There is no firmware update available. | No action needed. |
bluetoothFirmwareUpdateError |
An error occurred performing a Bluetooth firmware update. Reset your device and try again. | Reset the card reader, then try the update again. See Updating the card reader firmware for the reset steps. |
firmwareRetrievalError |
An error occurred fetching the firmware update. | Check your network connection, then try again. |
updatePartiallyApplied |
Failed to fully apply firmware update. Try again. | Try the firmware update again. |
updateNotApplied |
An error occurred applying the firmware update. | Try the firmware update again. |