---
url: /zoho-payments-whmcs/troubleshooting.md
description: >-
  Fixes for common Zoho Payments for WHMCS problems — the widget not loading,
  OAuth token errors, webhooks not processing, and license issues. Start with
  the Gateway Log.
---

# Troubleshooting

Most issues come down to a credential that doesn't match, a webhook that can't be reached, or a
license that isn't active. Start with the **Gateway Log** (**Utilities → Logs → Gateway Log**) —
it usually names the problem — then work through the section below.

## The widget won't load

If the customer clicks **Pay Now** but the embedded Zoho widget doesn't appear:

* **Check the Widget API Key.** Open **Setup → Payment Gateways → Zoho Payments** and confirm the
  **Widget API Key** matches the key from your Zoho Developer Space, with no stray spaces.
* **Check the Account ID.** Confirm the **Account ID** is your correct Zoho Payments Account ID.
* **Check the browser console.** Open your browser's developer console on the invoice page and look
  for errors when the widget tries to load — a blocked script or a rejected key shows up there and
  points you at the field to fix.
* **Confirm the Data Center.** An IN key won't work against the US data centre (or vice versa);
  make sure **Data Center** matches where your Zoho account lives.

## OAuth token errors

If the log shows token or authorisation failures, or payments can't be verified:

* **Check the Client ID and Client Secret.** Re-copy both from the **Zoho Developer Console** for
  the matching data centre and save them.
* **Check the redirect URI.** The redirect URI used when generating the token must be added to your
  application in the Developer Console. If it isn't, authorisation fails.
* **Regenerate the refresh token.** Use the **"Click Here to Generate Token"** helper link in the
  gateway settings to authorise again, then paste the fresh **refresh token** back into WHMCS and
  save. A revoked or stale refresh token is the most common cause.

## Webhooks not processing

If Payment Link payments aren't being marked paid automatically:

* **Check the Webhook URL.** In your Zoho Payments dashboard the webhook must point to
  `https://yourdomain.com/modules/gateways/zohopayments/webhooks/paylink_webhook.php`, using your
  real domain.
* **Check the Webhook Secret.** The secret in Zoho must match the **Webhook Secret** field in the
  gateway config exactly — a mismatch causes the signature check to fail and the event to be
  rejected.
* **Check SSL.** The webhook endpoint must be reachable over **valid HTTPS**. An expired or
  self-signed certificate stops Zoho from delivering events.
* **Review the Gateway Log** for the rejected event to confirm which of the above is at fault.

## License issues

If payments are being blocked:

* **Verify the key.** Confirm the **License Key** in the gateway config is correct and active.
* **Check the domain.** Your license is registered to a domain — make sure it matches the domain
  WHMCS is running on.
* Remember that while the license is inactive, **new payments are blocked** (the customer sees
  *"Online payment is temporarily unavailable. Please contact us to complete your order."*) but any
  **payment already made at Zoho is still recorded**. See [Licensing](/zoho-payments-whmcs/licensing).

## Related pages

* [Error reference](/zoho-payments-whmcs/errors) — the exact messages and what triggers them
* [Configuration](/zoho-payments-whmcs/configuration) — every field explained
* [Zoho OAuth setup](/zoho-payments-whmcs/guides/zoho-oauth) — app, refresh token, webhook
* [Licensing](/zoho-payments-whmcs/licensing) — how the license gates payments