--- url: /relypay-whmcs/troubleshooting.md description: >- Fix the most common RelyPay for WHMCS problems — sync mismatches, payment failures, routing that never fires, update failures and the ionCube loader error. --- # Troubleshooting Work through the section that matches your symptom. Each one lists what to check, in the order that resolves the problem fastest. If a customer error message is what you are chasing, look it up on the [Error reference](/relypay-whmcs/errors) first. ## Sync issues — files or components out of date If **Global Settings → Sync Manager** shows a **Sync Required** banner, or a checkout method is missing after a change, the deployed files no longer match what RelyPay expects. 1. Go to **Addons → RelyPay → Global Settings → Sync Manager**. 2. In the **Deployment Sync Status** table, use the per-component **Sync** action for any row that is not up to date, or run a full re-sync to fix everything at once. 3. Check the **Vendor Dependencies** table — a missing provider path means that provider's support files were not deployed; re-sync to restore them. 4. Open the **File Integrity** panel. It verifies deployed files against a signed snapshot and flags any tampered or missing file. Re-sync to redeploy anything it reports. When everything is healthy the banner reads *"All providers, sub-gateways, and deployed files are up to date."* ::: tip Keep it automatic Turn on **Auto-Sync on Admin Page Load** in Sync Manager so a mismatch is corrected the next time you open an admin page — you rarely have to sync by hand. ::: ![Sync Manager deployment status](/relypay-whmcs/img/relypay-troubleshooting-sync.png) *Addons → RelyPay → Global Settings → Sync Manager* ## Payments are failing When a customer cannot pay, or a payment starts but never completes, check these in order: 1. **Open [Transactions](/relypay-whmcs/features/transactions)** (**Addons → RelyPay → Transactions**). Filter by provider and status to see which provider handled the attempt and how it ended. This tells you whether the failure was at the provider or after the callback. 2. **Verify the provider credentials.** On **Addons → RelyPay → Providers**, open the provider and use **Test Connection**. Bad or expired keys are the most common cause. 3. **Confirm the webhook is set in the provider's dashboard.** Each provider's config page shows the exact **webhook URL** to paste and the events to subscribe to. If the webhook is missing, a payment can succeed at the provider but never finalise in WHMCS. 4. **Check the WHMCS Activity Log** (**Utilities → Logs → Activity Log**). Signature and verification problems are recorded there — for example *"Signature verification failed"* or *"Webhook signature mismatch"* — and point to a wrong or missing webhook secret. ::: warning SSL is required Provider webhooks only reach a secure endpoint. If your store is not served over HTTPS with a valid certificate, webhooks will fail and payments will not finalise. ::: ## Routing is not working A payment goes to the wrong provider, or a provider you configured is never used: 1. **Check your [routing rules](/relypay-whmcs/features/routing)** under **Addons → RelyPay → Routing**. RelyPay evaluates the four layers in a fixed order and only the first matching layer decides — so a broad currency or amount rule can win before the one you expected. Confirm the rule you want actually matches the currency or amount. 2. **Confirm the provider is enabled and fully configured.** A routing layer only fires when it names a provider that is both enabled and configured on **Providers**. A half-configured provider is silently skipped. 3. **Check the fallback chain.** If no currency, amount or volume rule matches, RelyPay uses the fallback — set separately for INR and non-INR. Make sure the fallback names a working provider. 4. **Activate the sub-gateway.** Routing only runs for methods a customer can actually select. Enable the matching sub-gateway under **Setup → Payment Gateways** — an unactivated sub-gateway never appears at checkout, so its routing never runs. ## Updates fail or the button is disabled Use **Global Settings → Update Status → Check for Updates**, then **Update Now**. If an update will not apply: 1. **Make the addon directory writable.** *"Addon directory is not writable"* means RelyPay cannot replace its own files — fix filesystem permissions on `modules/addons/relypay/`. 2. **Free up disk space.** A backup is always taken before an update. If the backup cannot be verified nothing is changed and you will see *"Backup verification failed"* — confirm `modules/addons/` is writable and there is free disk space. 3. **Confirm the license is active.** For a **Leased** license the module (and updates) work only while it is Active. For a **Lifetime** license, **Update Now** is blocked if your **Support & Updates** plan has lapsed — the current version keeps working; renew to install newer versions. See [Licensing](/relypay-whmcs/licensing). 4. **Retry transient failures.** *"Unable to check for updates. Could not reach the update server."* and download errors are usually network issues — check outbound HTTPS and try again. If an update ever fails partway, RelyPay automatically restores both files and database from the pre-update backup, leaving the install exactly as it was. ## "This product requires the ionCube PHP Loader" A fatal error mentioning the **ionCube PHP Loader** on activation or page load means the server is missing a compatible loader. RelyPay ships as an ionCube-encoded build and will not run without one. * Ask your host to enable **ionCube Loader 13.0.2 or newer** for your PHP version. * This is the same loader WHMCS itself requires, so a host already running WHMCS almost always has it — your host can confirm the installed version. See [Requirements](/relypay-whmcs/requirements) for the full server checklist. ::: info Still stuck? Note the exact message and where it appears (checkout, admin, activation), grab the matching row from [Transactions](/relypay-whmcs/features/transactions) or the Activity Log, and contact support. :::