Troubleshooting
Find your symptom below, or search the Error Message Index for the exact message on your screen. Messages are quoted exactly as the plugin shows them.
Setup problems
POS Linkly Reader is missing on the POS pay screen
- Check: is Enable/Disable ticked in the gateway settings? A disabled gateway hides Linkly on every till.
- Check: does the cashier's outlet list POS Linkly Reader in Additional Payment Option? See Enable Linkly on Outlets.
- Check: is the method's Status set to Enable under POS Payment Method?
- Fix: after changing any of these, reload the POS so it fetches the updated payment options.
The Linkly icon is missing from the POS header
The icon is only shown while the gateway is enabled. Enable it and reload the POS.
POS Linkly Reader disappeared after reactivating the plugin
Deactivating deletes the payment method; activating recreates it and adds it to all outlets. Remove it again from outlets without a terminal. See Installation.
Pairing problems
"Invalid linkly credentials."
The username or password for the current mode is empty. With Test mode on, fill Test Username and Test Password; with it off, fill Live Username and Live Password. See Test mode and credentials.
"Invalid secret key"
Linkly did not accept the pairing request.
- Re-read the pair code on the terminal — it may have changed.
- Make sure the credentials are correct for the mode.
- Make sure the terminal belongs to the same environment as Test mode (sandbox terminal with test mode on, production terminal with it off).
"POS Linkly Terminal Gateway is not enabled."
Enable the gateway in the gateway settings.
The Linkly icon dot is red after opening the POS
Either the till has never been paired (Linkly Not Connected.), or Linkly no longer accepts the saved pairing (The linkly terminal pairing is no longer valid…). In the second case the POS has already removed the old code. Enter the new pair code from the terminal.
The Linkly icon dot stays grey
The POS could not reach Linkly to check the pairing. Hover the icon for the reason (Unable to reach linkly: …). The saved pairing is kept, so check the internet connection and reload the POS.
Payment problems
"Linkly terminal is not connected. Please enter the terminal pair code…"
The cashier's till is not paired. Pair the terminal, then confirm the payment again. No order was created.
"Linkly terminal not connected" during a payment
Linkly rejected the till's pairing when the payment started, so nothing was charged. Enter the new pair code from the terminal and select Save & pay again — see If the terminal pairing is rejected.
The payment failed with a message from the terminal
The Confirmation box shows the terminal's own response (for example a declined card). Ask the customer for another card and select Pay again, or select Cancel and take payment another way. The order stays Pending payment.
"Unable to create payment please check your credentials"
Linkly rejected the payment request. Check the credentials and Test mode in the gateway settings, then re-pair the till.
"The payment was not started on the linkly terminal. Please try again."
Linkly has no record of the transaction reaching the terminal. Check that the terminal is on and online, then select Pay again.
"Payment not confirmed yet"
No result came back within five minutes. Check the terminal's screen or receipt:
- If the payment went through, select Check again — the POS picks up the approved result for the same transaction.
- Do not take the payment again until it is confirmed.
The order stayed "Pending payment"
That is expected until the terminal approves the card. Declined, cancelled, or unconfirmed payments leave the order pending. See Take a Linkly Payment.
Error Message Index
| Message | Where | Cause | Fix |
|---|---|---|---|
| Invalid linkly credentials. | Pairing, payment | Credentials for the current mode are empty | Fill credentials |
| Invalid secret key / Invalid secret key. | Pairing, payment | Linkly refused the pairing | Check pair code, credentials, mode |
| POS Linkly Terminal Gateway is not enabled. | Pairing | Gateway disabled | Enable the gateway |
| Invalid terminal pair code. / Invalid pair code | Pairing | Empty pair code | Enter the pair code |
| Security check failed! / Security check failed | Pairing, payment | The POS session is stale | Reload the POS and try again |
| Linkly terminal is not connected. Please enter the terminal pair code from the Linkly icon in the header before taking payment. | Pay screen | Till not paired | Pair the terminal |
| The linkly terminal pairing is no longer valid. Please enter a new pair code from the terminal. | Header icon, payment | Linkly rejected the saved pairing | Pair again |
| Unable to reach linkly: … | Header icon | Linkly could not be reached to check the pairing | Check the connection and reload the POS |
| Invalid token. | Payment | Linkly did not issue an access token | Check credentials and mode, re-pair |
| Unable to create payment please check your credentials | Payment | Linkly rejected the request | Check credentials and mode |
| The payment was not started on the linkly terminal. Please try again. | Payment | Transaction never reached the terminal | Check the terminal, Pay again |
| Payment failed. | Payment | Generic failure with no terminal text | Pay again or use another method |
| Invalid order id. | Payment | The order could not be found | Reload the POS and create the sale again |
| Woocommerce POS Linkly Reader Payment is activated but not effective… | WordPress admin | WooCommerce Point of Sale is inactive | Activate WooCommerce Point of Sale |
Still stuck?
Before opening a ticket, note:
- The plugin version (1.1.0) and your WooCommerce Point of Sale version.
- Whether Test mode is on.
- The exact message shown, and the order number if one was created.
- Whether the terminal showed the amount at all.
Then raise a ticket at webkul.uvdesk.com ↗.