Troubleshooting

This page covers common terminal payment issues and their solutions.

What you'll learn

How to diagnose device offline issues
What to do when payments time out
Common decline codes and their meanings
Connector update problems
How to export logs for support

Device Shows "Offline"

The connector has not sent a heartbeat to RevKeen Cloud in the last 5 minutes.

Possible causes and solutions:

Connector app is not running -- Check that the RevKeen Terminal Connector is running in your system tray (Windows) or menu bar (macOS). Restart it if needed.
No internet connection -- The connector needs internet access to maintain the connection to RevKeen Cloud. Verify your computer's internet connection.
Firewall blocking WebSocket -- The connector uses a WebSocket connection to wss://ws.revkeen.com. Ensure your network/firewall allows outbound WebSocket connections on port 443.
Connector crashed -- Restart the Terminal Connector application.

If the connector shows as connected in the system tray but the dashboard shows offline, try restarting the connector. The WebSocket connection may have silently dropped.

Payment Stuck on "Requested"

The terminal did not respond within 3 minutes. The payment will automatically time out.

Common causes:

Terminal is powered off or not connected to the network
WebLink app is not running on the terminal -- open it and ensure it shows "LISTENING (READY)"
Connector can't reach the terminal -- The connector and terminal must be on the same local network. Check that both are on the same Wi-Fi.
Firewall between connector and terminal -- Some corporate networks block device-to-device traffic on the LAN

Solution: Check that the terminal is on and reachable, restart the connector if needed, and try the payment again. The stuck payment will automatically time out after 3 minutes.

Payment Timed Out

The 3-minute timeout elapsed without a response from the terminal.

What to check:

Is the terminal powered on and showing the WebLink "LISTENING (READY)" screen?
Is the connector running and showing as Online in the dashboard?
Can the connector reach the terminal's IP on the local network?

If the terminal was processing a card when the timeout occurred, the card may still have been charged. Check the terminal's receipt printer or on-screen result, and check your gateway's transaction log before retrying.

Decline Codes

Terminal declines use the same decline code system as online payments. Common terminal-specific scenarios:

Scenario	Cause	Action
Card Read Error	Chip or contactless read failed	Ask customer to try again or use a different entry method
Insufficient Funds	Card does not have enough balance	Ask for a different card
PIN Incorrect	Wrong PIN entered	Customer can retry (usually 3 attempts)
Card Expired	Card's expiry date has passed	Ask for a different card
Lost or Stolen Card	Card reported to issuer	Do not attempt again -- ask for a different payment method
Call Issuer	Bank requires voice authorisation	Customer should contact their bank
Invalid Card	Card number not recognized	Try a different card
Restricted Card	Card type not accepted for this transaction	Try a different card

The dashboard payment progress overlay shows the specific decline reason and recommended action for each scenario.

Refund Requires Card Present

Some payment processors require the customer's card to be present for a terminal refund. If the refund fails with this error:

Ask the customer to present the same card used for the original transaction
The terminal will process the refund and display the result

If the customer no longer has the original card, contact your payment processor about processing a manual refund.

Connector Update Issues

Update Fails

If a connector update fails to apply:

Ensure the connector has internet access
Check that no payment is in progress (updates are blocked during active payments)
Try clicking Update again from the dashboard
As a last resort, uninstall and reinstall the connector from the releases page

Connector Won't Start After Update

If the connector doesn't start after an update:

Check the system event log (Windows) or Console app (macOS) for error messages
Try reinstalling the connector from the dashboard
Contact support with the log file

Exporting Logs for Support

If you need to contact support, gather the following:

Terminal serial number -- Found in the Terminal settings page or on the terminal's label
Connector version -- Shown in the Terminal settings page next to each connector
Transaction ID -- If the issue is with a specific payment, note the terminal payment attempt ID
Connector diagnostics -- The connector can upload diagnostic logs to RevKeen for support analysis

Frequently Asked Questions

Can I use the terminal without internet?

The connector requires internet to receive payment commands from RevKeen Cloud. However, the PAX terminal itself may support offline mode for certain transactions depending on your processor's configuration. Contact your payment processor for offline mode details.

Why does the terminal show a different amount than expected?

Verify the amount and currency in the payment request. Amounts are in minor units (pence/cents), so 5000 = £50.00. Check that the correct currency is selected.

The terminal processed the payment but the dashboard still shows "Requested"

This can happen if the connector lost internet after sending the command to the terminal but before receiving the result. The status will update when the connector reconnects, or when the 3-minute timeout triggers a status check. You can also check the terminal's receipt or your gateway dashboard to confirm the payment.

Can I use the terminal with a different payment gateway?

Terminal payments currently require NMI as the payment gateway. Support for additional gateways is planned.

Terminal Overview -- How terminal payments work
Device Management -- Monitor and manage your devices
Terminal API: Best Practices -- Developer tips for reliable terminal integrations

Troubleshooting

On this page