---
url: /payglocal-recurring-whmcs/installation.md
description: >-
  Step-by-step install for PayGlocal Recurring for WHMCS — upload the files,
  place your RSA keys, activate the gateway, fill in the settings, and take a
  sandbox test payment.
---

# Installation

This walks you through installing PayGlocal Recurring from files to first test payment. It takes a
few minutes if you already have your [PayGlocal RSA keys](/payglocal-recurring-whmcs/guides/payglocal-keys)
and your license key ready — grab those first, then follow the steps in order.

::: tip Before you start
Confirm your server meets the [Requirements](/payglocal-recurring-whmcs/requirements) (PHP 8.2+,
WHMCS 8.13+, ionCube 13.0.2+, SSL, and the daily cron), and have your PayGlocal **MID**, your two
`.pem` **RSA keys** with their **KIDs**, and your **license key** to hand.
:::

## Step 1 — Upload the module files

Extract the release zip and upload its **`modules/`** and **`includes/`** directories into your
WHMCS root, merging with the existing folders (don't overwrite unrelated files). This puts the
gateway, its callback handler, and the recurring-charge cron hook into place.

## Step 2 — Place your RSA keys outside the web root

Upload your two **RSA key `.pem` files** — your merchant private key and PayGlocal's public key —
to a secure directory **outside your web root** (for example `/home/user/keys/`, not inside
`public_html`). Make them readable by the web-server user only:

```
chmod 640 merchant_private.pem payglocal_public.pem
```

::: warning Keep private keys private
The private key must never be reachable over the web. Existing mandates are authorised against
these keys, so store them safely and back them up. Note the absolute path to each file — you'll
enter it in the settings.
:::

## Step 3 — Activate the gateway

In WHMCS, go to **Setup → Payment Gateways → All Payment Gateways**, find **PayGlocal Recurring**
in the list, and click it to activate.

![The All Payment Gateways list in WHMCS with PayGlocal Recurring](/payglocal-recurring-whmcs/img/payglocal-recurring-installation-gateways-list.png)
*Setup → Payment Gateways → All Payment Gateways*

The required JWT libraries install automatically on activation. If your server can't install them,
activation will report a problem — contact support and we'll help.

## Step 4 — Fill in the settings

The gateway now appears under **Setup → Payment Gateways → Manage Existing Gateways**. Open
**PayGlocal Recurring** and complete the fields: your **License Key**, **Merchant ID (MID)**, the
**private/public key file paths and their KIDs**, and the SI options (**maximum amount per
payment**, **days before due date to charge**, and **Test / Sandbox Mode**).

![The PayGlocal Recurring gateway configuration form](/payglocal-recurring-whmcs/img/payglocal-recurring-installation-config-form.png)
*Setup → Payment Gateways → PayGlocal Recurring*

Each field is explained on the [Configuration](/payglocal-recurring-whmcs/configuration) page.

## Step 5 — Save changes

Click **Save Changes**. Your license is checked at this point and whenever a payment is initiated —
if the [license](/payglocal-recurring-whmcs/licensing) is active, the gateway is ready to take
payments.

## Step 6 — Test in sandbox first

Set **Test / Sandbox Mode = Yes** and take a test payment before you go live, so you can confirm
the mandate is created and stored end to end. Use UAT keys/KIDs while in sandbox, then switch to
your production keys and **Test / Sandbox Mode = No** when you're ready. The
[going-live checklist](/payglocal-recurring-whmcs/guides/going-live) covers the switch.

## Related pages

* [Requirements](/payglocal-recurring-whmcs/requirements) — check your server first
* [PayGlocal key setup](/payglocal-recurring-whmcs/guides/payglocal-keys) — generate your RSA keys
* [Configuration](/payglocal-recurring-whmcs/configuration) — every setting explained
* [Licensing](/payglocal-recurring-whmcs/licensing) — enter and manage your key
* [Going live](/payglocal-recurring-whmcs/guides/going-live) — sandbox to production