Troubleshoot Terminal Payment Errors
When a payment terminal returns an error or a transaction behaves unexpectedly, this article explains what each message means and gives you the steps to resolve it. Each section uses the exact message text that appears in Zenoti or on the terminal so you can search for what you see.
Audience: Front desk staff and center administrators who process payments using payment terminals connected to Zenoti.
Before you begin
- Your center must have a payment terminal configured under Configuration > Payments > Process payments > Payment processor onboarding > Terminals.
- You need network access to Zenoti and an active connection between the terminal and your network.
- Have the terminal serial number available before contacting Zenoti Support β it speeds up case resolution.
Steps
"Failed to process payment. Failed to send message to POI. There may be a network issue or it may not have the websocket connected"
This message means the terminal (POI stands for "point of interaction" β the physical payment terminal) is offline or unreachable. Zenoti could not open a communication channel to the device.
To resolve this error:
- Check that both the terminal and the computer or iPad running Zenoti are on a stable network. Look for the network and cloud icons on the terminal's status bar β both should appear active.
- Restart the terminal by powering it off and back on, then reload Zenoti in the browser or app before trying again.
- If the error persists, restart the router or network switch at the center.
- If a network restart does not help, unpair and re-pair the terminal:
- Navigate to Configuration > Payments > Process payments > Payment processor onboarding > Terminals.
- Remove the terminal from the list, then add it again following the on-screen pairing steps.
- Check whether a firmware update is available for the terminal. Refer to the terminal manufacturer's documentation for how to check and install updates.
Once the connection is restored, this error clears automatically. A terminal replacement is only necessary if the error persists after all the steps above.
"Failed to save card details. Failed to process payment. Failed to send message to POI"
This message shares the same root causes as the connection error above β the terminal is offline, unpaired, stuck on an error screen, or experiencing weak Wi-Fi.
To resolve this error:
- Confirm that both the network icon and the cloud icon are showing on the terminal's status bar. A missing icon means the terminal has lost its connection.
- Check whether the terminal is stuck on an error or confirmation screen from a previous transaction. If it is, cancel or dismiss that screen on the terminal before retrying.
- Confirm the terminal is paired in Zenoti under Configuration > Payments > Process payments > Payment processor onboarding > Terminals.
- To rule out a router problem, connect the terminal (or the computer running Zenoti) to a mobile hotspot and retry the payment. If the payment succeeds on the hotspot, the issue is with your local network.
- If the router appears to be the cause, restart it and wait for all devices to reconnect before retrying.
"Cannot process payment while another transaction is in progress"
This message means the terminal believes a transaction is already open. Only one transaction can run at a time on a terminal.
To resolve this error:
- Wait for the current transaction to finish or cancel it from the POS before starting a new payment.
- If the terminal appears stuck β for example, showing a processing screen with no progress β restart it by powering it off and back on.
- After the terminal restarts, reopen the invoice in Zenoti and check the terminal status before retrying the payment.
Note: If the stuck transaction was partially processed, check the invoice in Zenoti before retrying to avoid duplicate charges.
If the deboard and onboard options in Configuration > Payments > Process payments > Payment processor onboarding > Terminals are not available to you, ask your organization administrator for the required permissions. After access is granted, deboard the old terminal and onboard the replacement.
Terminal shows the payment as approved, but Zenoti shows the guest still owes money
When a terminal shows "Approved" but the invoice in Zenoti still shows an amount due, the terminal authorized the payment but Zenoti did not receive the confirmation response. The transaction is recorded in Zenoti as Transaction Failed, and the guest has not been charged.
Likely causes:
- A network interruption or timeout occurred between the terminal approving and Zenoti receiving the result.
- The terminal lost connectivity immediately after processing.
- A browser session timeout or system lag prevented Zenoti from logging the response.
What to do:
- Do not charge the guest again straight away. The transaction failed to settle in Zenoti, so charging again immediately risks a duplicate.
- Reassure the guest that any temporary authorization hold on their card will be released automatically by their bank, usually within 3 to 7 business days depending on the bank β Zenoti did not capture the funds. Confirm this with the guest and monitor the transaction.
- Contact Zenoti Support with the following information:
- The invoice number.
- The time the payment was attempted.
- The terminal serial number.
Zenoti Support can verify whether the transaction settled and advise on next steps.
Terminal approves, but the computer shows an unexpected error β the iPad works fine
When the payment processes successfully on the terminal but the Zenoti web app on the computer displays an unexpected error, the terminal completed the transaction but the response did not reach the browser session.
Why this happens on the computer but not the iPad:
- The computer may have a slower or less stable network connection than the iPad.
- Stored browser sessions or cached data may be interfering with the response.
- A firewall or proxy on the computer's network connection may be blocking WebSocket traffic.
- The computer and the terminal may be on different network bands or network segments, preventing the response from routing correctly.
To resolve this:
- Clear the browser cache in the browser you are using on the computer, then reload Zenoti.
- Retry the payment. If the error reappears, open Zenoti in Google Chrome or in a private (incognito) window and try again.
- Check that the computer and the terminal are on the same Wi-Fi band and network segment. If they are on different bands (for example, 2.4 GHz vs. 5 GHz), move the computer to the same band as the terminal.
- If the problem repeats, contact Zenoti Support and include:
- The time the error occurred.
- The browser name and version.
- The invoice number.
Terminal shows 99% charged but will not open its interface
When a terminal is stuck at approximately 99% battery and the interface will not load, the device is likely downloading or applying a pending software update.
To resolve this:
- Connect the terminal to its original power adapter and plug it directly into a wall outlet. Do not use a power strip or a USB port on a computer β these may not provide sufficient power for the update to complete.
- Allow several minutes for the update to finish. The screen may appear frozen or show a progress indicator during this time.
- Do not disconnect the power cable or the network cable while the update is in progress β interrupting an update can leave the device in an unrecoverable state.
- Once the terminal returns to its normal home screen, retry the payment.
Tips
- Keep the terminal plugged in overnight. Terminals that are powered down or unplugged overnight may miss firmware updates that install automatically during low-traffic hours. Leaving the terminal connected ensures updates complete without interrupting business hours.
- Note the terminal serial number before an issue occurs. The serial number is typically printed on a label on the back of the device or accessible in the terminal's settings menu. Having it ready speeds up Zenoti Support cases significantly.
- Test the terminal with a small transaction after any network change. Whenever you move the terminal, change the Wi-Fi password, or swap a router, process a low-value test transaction before your next guest to confirm connectivity before you need it.
- Use Chrome on the desktop Zenoti interface. WebSocket connections that the terminal depends on behave most reliably in Chrome. Other browsers may have compatibility differences that cause sporadic communication failures.
- If a guest's card was declined, ask them to try a different card or payment method. A declined card is not the same as a connectivity failure β the terminal successfully communicated the decline to Zenoti. There is nothing to retry with the same card without the guest contacting their bank first.
Troubleshooting
| Symptom | Likely cause | Resolution |
|---|---|---|
| Error mentions "POI" and appears every time a payment is attempted | Terminal is unpaired or the pairing record is stale | Unpair and re-pair the terminal under Configuration > Payments > Process payments > Payment processor onboarding > Terminals |
| Error clears after restarting the terminal, but reappears within minutes | Intermittent Wi-Fi signal or DHCP lease expiry | Move the terminal closer to the router, or assign a static IP address to the terminal through your router settings |
| Zenoti shows "Transaction Failed" but the guest's bank shows a pending charge | Network dropped after terminal approved but before Zenoti confirmed | Do not retry the charge; contact Zenoti Support with the invoice number and terminal serial number |
| The computer browser shows an error but the same invoice works on the iPad | Browser cache, firewall, or wrong network band on the computer | Clear browser cache, retry in Chrome or a private window, and confirm the computer is on the same network band as the terminal |
| Terminal stuck at 99% battery, interface will not load | Pending firmware update | Plug into a wall outlet using the original adapter and wait; do not disconnect power until the terminal returns to its home screen |