---
url: /payglocal-whmcs/troubleshooting.md
description: >-
  Fix common PayGlocal for WHMCS problems — payments failing, key file errors,
  JWS verification failures, and a license that won't activate.
---

# Troubleshooting

Find your symptom and work the steps in order. Most problems come down to keys, paths, or environment mismatches — and they all leave a trail in the Gateway Log.

## Always check the Gateway Log first

**Utilities → Logs → Gateway Log.** Every PayGlocal attempt is recorded here. Open the most recent PayGlocal entry — it tells you which stage failed and points you at the fix below.

| Log entry | Stage | Go to |
| --- | --- | --- |
| *"Key file could not be read"* | Reading a `.pem` key | [Key file errors](#key-file-errors) |
| *"JWS verification failed"* | Verifying the callback signature | [JWS verification failed](#jws-verification-failed) |
| Status cross-check mismatch | Status API disagrees with the callback | Gateway trusts the status API; re-check MID and environment |
| License-inactive | License validation | [License won't activate](#license-won-t-activate) |

## Payments are failing

1. Confirm your **Merchant ID (MID)** in **Setup → Payment Gateways → PayGlocal**.
2. Check both **Key ID (KID)** values match the keys you're actually using.
3. Verify the two key **file paths** point at the right `.pem` files.
4. Use the **correct key pair for the environment** — UAT keys with Sandbox Mode on, production keys with it off.
5. Re-read the latest Gateway Log entry for the stage that failed.

## Key file errors

If the log points at reading a key file:

1. Confirm each **file path** is the absolute path to the `.pem`.
2. Ensure the file is **readable by the web-server user** (`chmod 640`, correct owner/group).
3. Confirm the file is present at that path and wasn't moved during an update or server change.

## JWS verification failed

A JWS verification failure means the signature on PayGlocal's callback couldn't be validated. This is the authoritative check — the callback is rejected and the invoice left untouched.

1. Make sure the **PayGlocal public key matches the environment** — UAT public key in sandbox, production public key when live.
2. Confirm the **PayGlocal Public Key ID (KID)** matches that public key.
3. Check the key hasn't been rotated or **expired** in the GCC dashboard; download the current Common Certificate if it has.

## License won't activate

If payments are disabled and the log or settings indicate the license isn't active:

1. Re-check the **License Key** in the gateway settings for typos or trailing spaces.
2. Confirm your server can make **outbound HTTPS requests to relyweb.co**.
3. Renew if a **Leased** license has lapsed.
4. **Save Changes** after correcting the key.

## Recurring invoices aren't being charged

If **PayGlocal Recurring** isn't auto-charging renewals:

1. Confirm the main **PayGlocal** gateway is **active and fully configured** — recurring inherits
   all its credentials, keys and test mode from it, and a configuration error there stops recurring.
2. Confirm **PayGlocal Recurring** is activated and the invoices use it as their **payment method**.
3. Confirm the **WHMCS daily cron is running** — the auto-charge runs from the daily cron.
4. Check the invoice is within the **Days Before Due Date to Charge** window and **not more than 30
   days overdue** — the cron skips invoices past that.
5. Check the amount doesn't exceed the mandate's **SI Maximum Amount Per Payment** ceiling — charges
   above the multiple are skipped.
6. Re-check the **Gateway Log** for the mandate status. A **revoked**, **exhausted**, or
   not-found mandate is deactivated automatically; the customer must authorise a new mandate on
   their next invoice.

## Related pages

* [Error reference](/payglocal-whmcs/errors) — what specific conditions mean
* [Configuration](/payglocal-whmcs/configuration) — every gateway field
* [PayGlocal key setup](/payglocal-whmcs/guides/payglocal-keys)
* [How recurring payments work](/payglocal-whmcs/features/recurring-payments) — mandates and the cron
* [Licensing](/payglocal-whmcs/licensing)
* [FAQ](/payglocal-whmcs/faq)