---
url: /payglocal-recurring-whmcs/troubleshooting.md
description: >-
  Fix common PayGlocal Recurring problems in WHMCS — failed payments, RSA key
  file errors, mandates not stored, the cron not charging, JWS verification
  failures, and license activation issues.
---

# Troubleshooting

Most problems with PayGlocal Recurring show up in one place, so start there: the **Gateway Log**
at **Utilities → Logs → Gateway Log**. Every payment attempt, mandate save, cron charge and
verification step is recorded there with the PayGlocal status and any error. Filter to
**PayGlocal Recurring**, open the most recent entry, and work from what it tells you. The sections
below map the symptoms you're likely to see to a concrete fix.

::: tip Always look at the Gateway Log first
Before changing any setting, read the latest Gateway Log entry for the failed attempt. It usually
names the exact cause — a rejected key, a status like `ISSUER_DECLINE`, or a missing mandate — and
saves you from guessing. See the [error reference](/payglocal-recurring-whmcs/errors) for what
each status means.
:::

## Payments are failing

If customers can't complete a payment, or a charge is logged as failed:

1. Open the **Gateway Log** and read the entry for the attempt — note the PayGlocal status.
2. Go to **Setup → Payment Gateways → PayGlocal Recurring** and verify your **Merchant ID (MID)**,
   both **Key IDs (KIDs)** and both **key file paths** are correct and free of typos or stray
   spaces.
3. Confirm you've paired the **correct keys**: your *merchant private key* and *PayGlocal's public
   key* — not two of the same, and not swapped between fields.
4. Check the **Test / Sandbox Mode** setting matches the keys you entered (UAT keys with sandbox
   on, production keys with it off).

If the log shows a decline status (for example `ISSUER_DECLINE` or `GENERAL_DECLINE`), the request
reached PayGlocal and the card or risk engine rejected it — that's a customer-side issue, not a
configuration one. The [error reference](/payglocal-recurring-whmcs/errors) explains each status.

## Key file errors

If the log mentions the key files can't be read or loaded:

* Make sure each **key file path** is an **absolute** server path (e.g.
  `/home/user/keys/merchant_private.pem`), not relative to the WHMCS folder.
* Confirm the `.pem` files actually exist at those paths and were uploaded intact.
* Ensure they're **readable by the web-server user** — set permissions to `chmod 640` and the
  correct owner/group.

::: warning Keep keys outside the web root
Store your `.pem` files in a directory **outside** the public web root so they can never be
downloaded over HTTP. See [PayGlocal key setup](/payglocal-recurring-whmcs/guides/payglocal-keys).
:::

## The mandate isn't stored after the first payment

The mandate is what lets future invoices charge automatically, so a missing mandate means renewals
won't run. If a first payment succeeded but no mandate was saved:

* Open the **Gateway Log** for that transaction and confirm PayGlocal returned a mandate on the
  authorisation.
* Check the invoice actually reached a **`SENT_FOR_CAPTURE`** (successful) status — a payment that
  was abandoned or declined never creates a mandate.
* The mandate table is created automatically on activation, so you don't need to build it — if the
  log shows a mandate but nothing was stored, contact support with the log entry.

## The cron isn't charging renewals

Automatic renewals depend on the **WHMCS daily cron**. If invoices aren't being charged on their
own:

1. Confirm the **WHMCS daily cron is actually running** — check **Utilities → System → System
   Health Status** (or your server's cron) for a recent successful run.
2. Check your **Days Before Due Date to Charge** window under the gateway settings — the cron only
   attempts invoices due within that many days, so an invoice further out simply hasn't been picked
   up yet.
3. Make sure the client has an **active mandate** — without one, there's nothing to charge against.
4. Look for the cron's own entries in the **Gateway Log**; they'll show which invoices it tried and
   why any were skipped (for example, a charge above the mandate maximum is skipped by design).

See [How recurring mandates work](/payglocal-recurring-whmcs/features/recurring-mandates) for the
amount guard and the one-mandate-per-client rule.

## "JWS verification failed"

PayGlocal signs its callbacks, and the gateway verifies that signature. A verification failure
almost always means a **key or environment mismatch**:

* The **PayGlocal public key must match your environment** — UAT keys for sandbox, production keys
  for live. Verifying a production callback with UAT keys (or vice versa) fails.
* The **KID must match the key** you configured — re-check both **Key ID** fields against the GCC
  dashboard.
* Check for an **expired or rotated key** in the PayGlocal **GCC dashboard**; if a key was
  regenerated, download the current `.pem` and update the path and KID.

## The license won't activate

Payment processing is disabled while the license is inactive, so this blocks live charges:

* Re-check the **License Key** in **Setup → Payment Gateways → PayGlocal Recurring** for typos or
  trailing spaces.
* Ensure your server can make **outbound HTTPS connections to relyweb.co** — a firewall or proxy
  blocking that stops activation.
* If both look right, contact support with the details.

See [Licensing](/payglocal-recurring-whmcs/licensing) for how the license-gated feature works.

## Related pages

* [Error reference](/payglocal-recurring-whmcs/errors) — what each Gateway Log status means
* [FAQ](/payglocal-recurring-whmcs/faq) — quick answers to common questions
* [Configuration](/payglocal-recurring-whmcs/configuration) — activate, upload keys, fill fields
* [Settings reference](/payglocal-recurring-whmcs/settings) — every gateway field explained
* [PayGlocal key setup](/payglocal-recurring-whmcs/guides/payglocal-keys) — generate your RSA keys
* [Going live](/payglocal-recurring-whmcs/guides/going-live) — sandbox-to-production checklist