Troubleshooting POS App Connection with Ayden Terminal

Slow Connection or Red Retry Icon in Device Manager Screen

The Adyen terminal is always on the home screen if the connection is established. If the terminal is inside the admin menu, select X in the Adyen terminal to get back to the home screen and retry the connection from the iPad device manager screen.

Connect the iPad and Adyen terminal to the same Wi-Fi network. In some cases, the iPad has switched to the nearest available network.

Adyen terminal network IP changed and is different from the one used to pair it with iPad. Reconnect the Adyen terminal with the new IP.

The Wi-Fi network is a 2.4GHz network as most Adyen devices don't support 5GHz.

Run the below diagnostics in the terminal by choosing Network > Diagnostics option to verify it gets green tick marks. This confirms that the terminal is connected to the valid network and can communicate with the Adyen backend.

• PSP connection
• Terminal API
• Endpoint

Check the logs using View Logs in the info icon near IF YOU DO NOT SEE YOUR TERMINAL CONNECTED. CLICK HERE FOR INSTRUCTIONS and scroll to the bottom of the interstitial. The logs give the error causing the connection failure.

• In case of a CERT-NAME-MISMATCH error code, look for the certificate name seen next to this code to verify if it's a valid one. If not, reach out to the Adyen support team to resolve this issue.

Another reason for this can be that there was a glitch in the config update. (Refer to this Adyen support ticket). Try to update the config by 9 > green > Config > Admin PIN > Update. If the terminal is up to date and the issue still exists, remove the config and reboard the terminal by 9 > green > Config > Admin PIN > Remove/Reset.

Error Message: 'Incorrect Terminal Assignment. Expected <XYZ> found <ABC>'

The POS expects the terminal gateway to be XYZ, but the terminal is configured for gateway ABC.

Verify that the terminal is assigned to the correct store configured with the 'Terminal Gateway ID' in CMS > Payment Gateways > Adyen.

Make sure the store-specific gateway isn't set up with a different terminal gateway or payment gateway. Store-specific settings override the default settings.

Error Message: ‘Unauthorized, Nexo Service: crypto error (9)’

Make sure the Adyen terminal API passwords in CMS match the passwords in the Adyen portal for the specific terminal. Mismatched passwords can cause this issue. If the problem persists, try resetting the credentials.

Error Message 'The request timed out.'

For iOS 14 and later, make sure the POS has been granted "Local Network" permission to connect to external devices via a local network. In Settings, go to Privacy > Local Network to see a list of every app granting access and confirm if POS is provided with the same. For more information, see Check app permissions.

If the issue persists, review the network security configured in the store. For starters, make sure the SSID is set up correctly and that it allows host-host connections.

Error Message: "Unknown runner error: (10009) 'merchantAccount' element missing or empty."

This error is related to SDK integration. Check the register configuration and make sure that the Card Reader > Integration Type is set to Local API to resolve this issue.

Error Message: ‘The terminal is unreachable at the moment, please retry again'

This can happen if the terminal has a battery charge of less than 5%. Charge the terminal and try again. If this issue persists, run the below diagnostics in the terminal by choosing Network > Diagnostics option to verify it gets green tick marks. This confirms that the terminal can carry out the payment transaction.Verify if a blue tick mark exists for the terminal in the Device Manager screen. Select the info icon for the terminal and select Run Diagnostics in the middle to check if the connection works from the app to the terminal. Additionally, verify your device has internet connectivity via the Settings app.

• PSP connection
• Terminal API
• Endpoint
• Verify if the terminal is connected to the Device Manager screen.

Error Message: 'Nexo Service: no shared key configured' or 'At SaleToPOIRequest, field PaymentRequest: Missing At SaleToPOIRequest: Missing'

These Adyen-generated errors can happen due to: terminal API configuration (Encryption Key Identifier, Encryption Key Passphrase, Encryption Key Version) from the Adyen portal not being updated correctly in the Adyen terminal or device region not properly set.

• Go to Settings > General > Language and Region. Make sure the device and terminal Region match.
• Reboot the terminal and select Admin Menu > Config > Update to get the latest configuration from the portal and retry the transaction.
• Reach out to Adyen support if the issue persists. This issue was seen in Adyen firmware 1.43 version, which was fixed in the 1.45 version update.

Error Message: ‘Unauthorized, Nexo Service: crypto error (6)

The Payment Gateway not being properly configured in CMS (Integrations > Payment Gateway) or incorrect credentials in CMS can cause this issue. It can also result from the terminal not syncing with the latest credentials from the portal. Try these steps:

• Verify Adyen API Credentials: Make sure the Adyen terminal API passwords set in CMS match the ones in the Adyen portal for the specific terminal. A mismatch can cause issues. If the credentials don't match or if the issue persists, consider resetting your credentials.
• Update Terminal Configuration:If the problem continues, go to Config > Update in the CMS to fetch the latest configuration from the portal and retry the transaction.

Unable to Cancel/Abort a Payment Even After 150 Seconds

It's recommended to set the payment Terminal Request Timeout Interval In Seconds setting in the Payment Gateway configuration in CMS to 150 seconds. This time interval decides how long the POS will wait for a response for the payment from the terminal. A misconfiguration of this setting to a higher value (>150 seconds) restricts the user from canceling and aborting the payment until the timeout interval from the POS.

Error Message: 'Error in processing your request

POS can show the 'Error in processing your request' prompt if the terminal hasn't finished a previously requested task. Such tasks include:

• Processing previously applied card tenders after consecutively adding multiple card tenders
• Processing transaction from another register.
• Software update

In this case, wait a moment for the terminal to finish processing before applying additional card tenders. If the error still occurs, restart your terminal.

Error Message: 'Terminal Response Body Encryption Error'

If you see this message on the POS:

Additionally, if you check the register vitals in CMS and receive the following Payment Status Response as 'Terminal Response Body Encryption Error':

Then, use the following steps for troubleshooting:

• Go to your Adyen Gateway Console.
• Find Store > Terminals > Terminal Settings.
• Make sure that the fields set here match what's been provided in the CMS. If these values are blank, provide the same values used in CMS under Payment Gateways > Terminal Configuration:
  • Terminal Key Identifier
  • Terminal Key Passphrase
  • Terminal Key Encryption Version

In Staging / Test Environments, Certain Amounts Are Reserved for Simulating Errors

Refer to Adyen's documentation for a list of specific amounts and error reasons used in test environments.

• Update Option Shows 'No Update Available': This can occur if the terminal isn't connected to the internet. Verify that the connected Wi-Fi network has internet access.
• Software Version Not Up-to-Date: The terminal software sometimes isn’t updated due to a configuration issue in the Adyen backend. Contact the Adyen POS team to make sure the terminal is upgraded to the latest version.
• Offline Transactions Not Processing: Offline EMV payments depend on the card type, which can result in payment rejections. Make sure the offline payment limit is configured in the Adyen Customer Area. Offline Data Authentication failure can also block transactions. This feature is usually turned off in test environments to make testing easier. But it's needed for Store and Forward transactions in the USA. Contact Adyen Support to adjust this setting.
• Blank Black Screen on Terminal: Press the green "O" to power on the terminal. If unresponsive, connect it to a power source, and it will automatically power on after it’s charged.
• Sudden Loss of Connection: If the connection drops unexpectedly, verify the IP addresses on both devices and check device vitals for any network-related issues.
• Transaction Interruption During Update: Forced updates during a transaction will cause an error. The terminal will display the canceled transaction amount, date, time, and reference IDs.

Error Message: 'MessageHeader.POIID: NotAllowed Value:...'

If you see the following message on the POS:

This occurs if the terminal topology is set to 1:1 and the IP addresses of payment terminals are static. Verify that the two payment terminals in the context have differing IP addresses.

Tips: Networking Recommendation from Adyen docs (updated on an ongoing basis).

Error Message: 'Validation failed: Total amount is lower than configured min amount.'

This error occurs if the refund amount is less than the minimum amount configured in the Adyen console. To resolve this issue, adjust the minimum amount setting in the Adyen console to $0.01. This will allow the refund to proceed without validation errors.