---
url: /payglocal-whmcs/installation.md
description: >-
  Install PayGlocal for WHMCS — upload the module, place your RSA keys, activate
  the gateway (and optionally PayGlocal Recurring), fill the settings, and take
  a sandbox test payment.
---

# Installation

Get PayGlocal from files to a working checkout: upload, place keys, activate, configure, and test in sandbox. Do these in order — the keys must be in place before you activate.

**Prerequisites:** a server that meets the [Requirements](/payglocal-whmcs/requirements), your [PayGlocal keys](/payglocal-whmcs/guides/payglocal-keys) generated and downloaded, and your **Merchant ID (MID)** and **License Key** to hand.

## 1. Upload the module

Merge the module's `modules/` and `includes/` directories into your WHMCS root, alongside your other gateways. The package ships **both gateways** (`payglocal.php` and `payglocalrecurring.php`), the shared `payglocal/` code directory, both callback handlers, and the recurring hook loader (`includes/hooks/payglocalrecurring_cron.php`).

## 2. Place your RSA keys outside the web root

Upload your two `.pem` files — **merchant private key** and **PayGlocal public key** — to a directory outside the web root, then lock them down:

```
chmod 640 /home/user/keys/merchant_private.pem
chmod 640 /home/user/keys/payglocal_public.pem
```

::: warning Keep private keys out of the web root
Never place a key under `public_html`/`httpdocs`. Use a path like `/home/user/keys/` and point the gateway at each file by its absolute path.
:::

## 3. Activate the gateway

**Apps & Integrations → PayGlocal → Activate.** The gateway installs the JWT/crypto libraries it needs on first activation. PayGlocal then appears on **Setup → Payment Gateways** under **Manage Existing Gateways**.

![Activating PayGlocal from Apps & Integrations](/payglocal-whmcs/img/payglocal-whmcs-installation-activate.png)
*Apps & Integrations → PayGlocal*

## 4. Fill in the settings

**Setup → Payment Gateways → PayGlocal.** Enter your **License Key**, **Merchant ID (MID)**, and the **path and KID** for each key. Set **Test / Sandbox Mode** to **Yes** for now. See [Configuration](/payglocal-whmcs/configuration) and the [Settings reference](/payglocal-whmcs/settings).

## 5. (Optional) Activate PayGlocal Recurring

For automatic renewals, also activate **PayGlocal Recurring** under **Apps & Integrations → PayGlocal Recurring → Activate**. It reuses every credential from the main **PayGlocal** gateway — you set only its two SI options (**SI Maximum Amount Per Payment** and **Days Before Due Date to Charge**).

::: warning Configure PayGlocal first
PayGlocal Recurring reads its license, Merchant ID, RSA keys and test mode from the main **PayGlocal** gateway at runtime. **PayGlocal must be activated and fully configured first**, or the recurring gateway shows a configuration error. Recurring also needs the **WHMCS daily cron** running to charge invoices. See [How recurring payments work](/payglocal-whmcs/features/recurring-payments).
:::

## 6. Save

Click **Save Changes**. PayGlocal is now a live payment option on your invoices.

## 7. Verify — take a sandbox test payment

Set **Test / Sandbox Mode = Yes**, generate a test invoice, and complete payment:

1. Confirm redirection to the hosted PayCollect checkout.
2. Complete the sandbox payment and return to WHMCS.
3. Verify the invoice status transitions to **Paid**.
4. Proceed to the [going-live guide](/payglocal-whmcs/guides/going-live).

::: tip Something not right?
Open **Utilities → Logs → Gateway Log** — it records each payment attempt and is the fastest way to see why a test didn't complete. See [Troubleshooting](/payglocal-whmcs/troubleshooting).
:::

## Related pages

* [Requirements](/payglocal-whmcs/requirements) — confirm your server and account
* [PayGlocal key setup](/payglocal-whmcs/guides/payglocal-keys) — generate your RSA keys
* [Configuration](/payglocal-whmcs/configuration) — fill in the gateway settings
* [Settings reference](/payglocal-whmcs/settings) — every field explained
* [How recurring payments work](/payglocal-whmcs/features/recurring-payments) — set up automatic renewals
* [Going live](/payglocal-whmcs/guides/going-live) — switch from sandbox to production