---
url: /payglocal-whmcs/errors.md
description: >-
  What PayGlocal for WHMCS error conditions mean — key file, JWS verification
  and license-inactive behaviour — and how to resolve each.
---

# Error reference

Diagnose PayGlocal gateway conditions and resolutions. All payment attempts and errors are
recorded in **Utilities → Logs → Gateway Log**.

## Payment and callback conditions

| Condition | What it means | How to resolve |
| --- | --- | --- |
| **Key file could not be read** | The gateway couldn't open a `.pem` key at the configured path. | Check the absolute path, that the file exists, and that it's readable by the web-server user (`chmod 640`). |
| **JWS verification failed** | The signature on PayGlocal's callback couldn't be validated. | Confirm the PayGlocal public key and its KID match the environment (UAT vs production) and that the key hasn't been rotated or expired in the GCC dashboard. |
| **Status cross-check mismatch** | The signed callback and PayGlocal's status API report different statuses. | The gateway trusts the status API value and logs the mismatch. Re-check MID and environment if the outcome looks wrong. |
| **Wrong environment / keys** | UAT keys are in use with Sandbox Mode off, or production keys with it on. | Match the key pair and KIDs to the mode: UAT keys with Sandbox = Yes, production keys with Sandbox = No. |

## Transaction statuses

PayGlocal returns a status with each callback and status check; the gateway logs it and acts on it.
These are the statuses you'll see in the Gateway Log:

| Status | Meaning | Gateway action |
| --- | --- | --- |
| `SENT_FOR_CAPTURE` | Payment successful and captured (PayCollect). | Invoice marked **Paid**. |
| `AUTHORIZED` | Recurring mandate authorised / SI charge succeeded. | Invoice marked **Paid**. |
| `CREATED` | Transaction created, not yet at a final state. | Logged as pending. |
| `INPROGRESS` | Still being processed. | Logged as pending. |
| `ABANDONED` | Customer left checkout without completing. | Logged as failed; invoice stays unpaid. |
| `ISSUER_DECLINE` | Declined by the customer's issuing bank. | Logged as failed. |
| `CUSTOMER_CANCELLED` | Customer cancelled the payment. | Logged as failed. |
| `AUTHENTICATION_TIMEOUT` | 3-D Secure / OTP authentication timed out. | Logged as failed. |
| `GENERAL_DECLINE` | Declined by the risk engine. | Logged as failed. |
| `REQUEST_ERROR` | Invalid request data. | Logged as failed. |
| `SYSTEM_ERROR` | PayGlocal system issue. | Logged as failed. |
| `CONFIG_ERROR` | Merchant/gateway configuration problem. | Logged as failed. |

## License-inactive behaviour

* **Payment impact:** New PayGlocal payments can't be *started* while the license is inactive.
* **In-flight payments:** A payment already completed at PayGlocal is still verified and recorded, so a paid customer never has an uncredited invoice.
* **Validation check:** Verification runs against `relyweb.co`.
* **Recovery:** Processing restores immediately once a valid license is saved.

### Resolution steps

1. Verify the **License Key** in **Setup → Payment Gateways → PayGlocal**.
2. Confirm outbound HTTPS connectivity to `relyweb.co`.
3. Renew lapsed licenses via your client area, then click **Save Changes**.

## Recurring (Standing Instructions) conditions

| Condition | What it means | How to resolve |
| --- | --- | --- |
| **Shared module files could not load** | PayGlocal Recurring couldn't load the shared `modules/gateways/payglocal/` code. | Ensure the complete PayGlocal module is installed and its files are readable by the web-server user. |
| **Main PayGlocal gateway not configured** | Recurring reads credentials from the main **PayGlocal** gateway, which isn't active or configured. | Activate and fully configure **PayGlocal** first, then save the recurring gateway. |
| **Charge skipped — above maximum** | The invoice amount exceeds the mandate's **SI Maximum Amount Per Payment** ceiling. | Charge the invoice manually, or raise the SI maximum multiple for future mandates. |
| **Mandate inactive / exhausted / not found** | The stored mandate is no longer usable at PayGlocal. | The mandate is deactivated automatically; the customer authorises a new mandate on their next invoice. |

## ionCube

PayGlocal requires the **ionCube Loader** extension. If missing or outdated (< 13.0.2), the
module will not initialize. See [Requirements](/payglocal-whmcs/requirements).

## Related pages

* [Troubleshooting](/payglocal-whmcs/troubleshooting) — step-by-step fixes
* [How recurring payments work](/payglocal-whmcs/features/recurring-payments)
* [Configuration](/payglocal-whmcs/configuration)
* [Licensing](/payglocal-whmcs/licensing)
* [Requirements](/payglocal-whmcs/requirements)