---
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

Identify your symptom and follow the corresponding resolution steps. Begin troubleshooting in the **Gateway Log** (**Utilities → Logs → Gateway Log**). For error definitions, see [Error reference](/zoho-payments-whmcs/errors).

## The widget won't load

Customer clicks **Pay Now** but the embedded widget doesn't appear:

1. **Widget API Key:** Verify the key in **Setup → Payment Gateways → Zoho Payments** matches Zoho Developer Space without whitespace.
2. **Account ID:** Ensure the entered **Account ID** matches your Zoho Payments account.
3. **Browser console:** Inspect the invoice page console for blocked scripts, CORS errors, or rejected keys.
4. **Data Center:** Verify the configured **Data Center** (`IN` vs `US`) matches your credentials region.

## OAuth token errors

Log shows token/authorisation failures, or payments can't be verified:

1. **Credentials validation:** Re-copy **Client ID** and **Client Secret** from the **Zoho Developer Console** for your data centre and save.
2. **Redirect URI:** Confirm the redirect URI is added to your OAuth app in the Developer Console.
3. **Refresh token renewal:** Click *"Click Here to Generate Token"*, re-authorise, and paste the fresh token into WHMCS.

## Webhooks not processing

Payment Link payments aren't marked paid automatically:

1. **Webhook URL:** Verify Zoho points to `https://yourdomain.com/modules/gateways/zohopayments/webhooks/paylink_webhook.php`.
2. **Webhook Secret:** Ensure the secret in WHMCS matches Zoho's webhook secret exactly to pass HMAC-SHA256 signature verification.
3. **SSL validation:** Ensure your domain serves a valid, unexpired HTTPS certificate.
4. **Gateway Log:** Inspect log entries to identify specific rejected events or signature errors.

## License issues

Payments are being blocked:

1. **Verify key:** Check that the **License Key** in gateway settings is active in your relyweb.co account.
2. **Domain match:** Ensure your WHMCS installation domain matches the licensed domain.

* **Checkout behavior:** While inactive, new checkouts show:
  > *"Online payment is temporarily unavailable. Please contact us to complete your order."*
* **In-flight safety:** In-progress transactions completed at Zoho are verified and applied. 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