PayGlocal for WHMCS
Documented release: 1.1.6
Licence product slug: payglocal-payment-gateway
Gateway file: modules/gateways/payglocal.php
Callback file: modules/gateways/callback/payglocal.php
1. Overview
PayGlocal for WHMCS connects unpaid WHMCS invoices to PayGlocal's hosted PayCollect checkout. The module encrypts and signs payment-initiation requests, redirects the customer to hosted checkout, verifies signed callbacks, checks the invoice and amount, and applies a successful transaction to the matching WHMCS invoice.
This release supports customer-initiated invoice payments. It does not claim automatic recurring card charging, token storage or mandate charging. WHMCS can generate renewal invoices, and the customer can pay each invoice through PayGlocal.
2. Compatibility and requirements
- WHMCS 8.x or a compatible WHMCS 9.x release
- PHP 7.4 or newer
- PHP cURL and OpenSSL extensions
- HTTPS-enabled WHMCS installation
- Correct WHMCS System URL
- Active PayGlocal merchant account
- PayGlocal Merchant ID and both Key IDs
- PayGlocal public key and merchant private key in PEM format
- Active AngleModules licence for
payglocal-payment-gateway
3. Before installation
- Back up WHMCS files and database.
- Obtain PayGlocal UAT credentials before configuring production.
- Store PEM files outside the public web root with restrictive permissions.
- Prepare a low-value UAT invoice using fictional customer information.
- Confirm the WHMCS System URL uses the hostname licensed in AngleModules.
4. Installation
- Extract the module release locally.
- Upload the included
modulesdirectory into the WHMCS root. - Open System Settings → Payment Gateways → All Payment Gateways.
- Activate PayGlocal.
- Open the PayGlocal gateway settings and enter the AngleModules licence key.
- Save, reload the page and confirm that Licence Status is ACTIVE.
- Configure PayGlocal credentials and select UAT/Sandbox.
5. AngleModules licensing
The licensing endpoint, product slug and RSA public verification key are embedded. The administrator enters only the licence key in the PayGlocal gateway settings.
The licence is bound to the hostname from the WHMCS System URL. A signed local response may be accepted during the server-defined offline grace period. Never distribute the AngleModules private signing key.
| Status | Meaning | Action |
|---|---|---|
| ACTIVE | Key, product, domain and entitlement were verified | Continue with UAT testing |
| INVALID_KEY | The licensing database cannot find the submitted key hash | Confirm the exact key and licensing database |
| PRODUCT_MISMATCH | The key belongs to another module | Issue it for payglocal-payment-gateway |
| DOMAIN_MISMATCH | The response hostname differs from the WHMCS hostname | Correct System URL or reset the activation |
| ACTIVATION_LIMIT | No production activation is available | Reset an old activation or upgrade the licence |
| EXPIRED/SUSPENDED | The licence entitlement is not active | Renew or reactivate the licence |
6. Gateway settings
| Setting | Purpose |
|---|---|
| AngleModules Licence Key | Commercial licence and live validation status |
| Merchant ID | PayGlocal merchant identifier |
| PayGlocal Public Key ID | ID associated with PayGlocal's public key |
| Merchant Private Key ID | ID associated with the merchant signing key |
| PayGlocal Public Key File | Absolute path to PayGlocal's PEM public key |
| Merchant Private Key File | Absolute path to the merchant PEM private key |
| Environment | UAT/Sandbox or Production endpoint |
| Payment Button Text | Customer-facing invoice payment action |
| Debug Logging | Optional sanitised WHMCS gateway diagnostics |
Values such asadminare not valid key-file paths. Use an absolute server path such as/home/account/secure/payglocal-public.pem. Never put the merchant private key in a public download directory.
7. Callback configuration
Give PayGlocal the HTTPS callback endpoint:
https://YOUR-WHMCS-DOMAIN/modules/gateways/callback/payglocal.phpThe callback must remain publicly reachable by PayGlocal. Do not protect it with a browser login, but keep WHMCS maintenance and firewall rules compatible with PayGlocal delivery.
8. Payment flow
- The customer opens an unpaid invoice and selects PayGlocal.
- The module verifies the AngleModules licence.
- The module creates a unique WHMCS merchant transaction reference.
- Invoice and billing data are encrypted into a PayGlocal request.
- The request digest is signed with the merchant private key.
- The customer is redirected to PayGlocal hosted checkout.
- PayGlocal sends a signed callback.
- The module verifies the signature, merchant, invoice, transaction and amount.
- WHMCS records the payment and marks the invoice paid when appropriate.
9. Required sales features
| Feature | Audience | Description |
|---|---|---|
| Native WHMCS integration | General | Accept PayGlocal payments through the standard WHMCS invoice workflow. |
| Hosted PayGlocal checkout | Client | Customers continue from their WHMCS invoice to PayGlocal's hosted payment page. |
| Automatic invoice confirmation | Admin | Verified payments are applied to the correct WHMCS invoice. |
| RSA-signed callback verification | Admin | Callback tokens are cryptographically verified before payment is accepted. |
| Invoice and amount matching | Admin | Invoice reference and paid amount must match before recording the transaction. |
| Duplicate-payment protection | Admin | WHMCS transaction checks prevent duplicate crediting. |
| Encrypted payment requests | General | Payment-initiation data is encrypted and signed before transmission. |
| UAT and production modes | Admin | Switch between test and live PayGlocal environments. |
| Sanitised debug logging | Admin | Optional diagnostics redact keys, signatures and tokens. |
| Integrated AngleModules licensing | Admin | Enter the licence key and see its status inside gateway settings. |
10. Sales-page screenshots
Use fictional UAT information and redact every key, Merchant ID, customer identity and complete transaction reference.
| Screenshot | Caption | Show safely |
|---|---|---|
| Gateway configuration | Configure PayGlocal and verify the AngleModules licence from WHMCS. | Active badge, environment, button text and debug option |
| Customer invoice | Customers can select PayGlocal directly from an unpaid WHMCS invoice. | Fictional invoice and PayGlocal selection |
| Payment action | A clear payment action starts secure hosted checkout. | Demo amount, currency and payment button |
| Hosted checkout | Customers complete payment through PayGlocal's hosted experience. | UAT only and only when PayGlocal permits publication |
| Paid invoice | Verified transactions are recorded against the matching invoice. | Demo paid status and sanitised reference |
| Gateway log | Sanitised diagnostics support safe troubleshooting. | Successful initiation and callback status with redactions |
11. Support terms
Technical support is provided while the AngleModules licence and applicable support entitlement remain active. Support covers installation guidance, configuration assistance, licensing issues, confirmed module defects and compatibility problems involving supported WHMCS and PHP versions.
Support does not include PayGlocal merchant approval, KYC, settlement disputes, chargebacks, custom API development, server administration, WHMCS customisation or conflicts caused by third-party modifications. PayGlocal controls merchant eligibility, enabled currencies, transaction approval, settlement and production credentials.
Support may request sanitised WHMCS gateway logs, PHP errors and environment details. Never send private keys, full credentials, cardholder information or complete licence keys.
12. Refund terms
Because the product is downloadable software containing licensable source code, purchases are generally non-refundable after download, activation or production use. A refund may be considered for a duplicate payment, an undownloaded incorrect licence, a reproducible defect that prevents the primary advertised functionality and cannot reasonably be corrected, or where applicable law requires it.
Refunds are not provided because PayGlocal rejects or delays merchant approval; a merchant account lacks a currency, country, card type or payment method; production credentials have not been issued; server requirements are not met; files were incorrectly installed or modified; or automatic recurring charging was expected despite not being advertised.
Eligible requests must be submitted within seven days with sufficient diagnostic information. Approved refunds are returned through the original method where technically possible. These terms require legal review and do not limit rights that applicable law does not permit a seller to exclude.
13. Frequently asked questions
What does the module do?
It connects WHMCS invoices to PayGlocal hosted checkout and applies successfully verified payments to the matching invoice.
Does WHMCS collect card information?
No. Customers complete payment within PayGlocal's hosted environment.
Does it mark invoices paid automatically?
Yes, after the signed callback, invoice, merchant, transaction and amount pass validation.
Does it support automatic recurring charges?
No. Customers can pay WHMCS-generated renewal invoices through PayGlocal. Automatic mandate or token charging is not included.
Which currencies are supported?
The module sends the WHMCS invoice currency. Acceptance depends on currencies enabled for the merchant by PayGlocal.
Can it be tested before production?
Yes. Use UAT/Sandbox with PayGlocal UAT credentials and a fictional test invoice.
Are production credentials separate?
Normally yes. Use the production Merchant ID, Key IDs and PEM files supplied or approved by PayGlocal.
Where should PEM files be stored?
Outside the public web root, readable only by the required server user.
Which PHP extensions are required?
PHP cURL and OpenSSL are required.
How are callbacks protected?
The module verifies PayGlocal's RSA-signed response token before applying payment.
What happens when a callback is delivered twice?
WHMCS duplicate-transaction checks prevent the same transaction from being credited twice.
Can the payment button be renamed?
Yes. Configure the text in the PayGlocal gateway settings.
Where is the AngleModules licence entered?
Inside the PayGlocal gateway settings. No separate addon module is required.
What happens when licensing is temporarily unavailable?
A previously verified signed response may be used during its offline grace period. A new installation needs online validation.
Does AngleModules control PayGlocal approval or settlement?
No. Merchant onboarding, payment acceptance and settlement remain controlled by PayGlocal.
14. Troubleshooting
Licence status is Missing
Save the licence key, confirm the updated gateway files are installed and reload the page. No separate addon is required.
Licence status is Invalid Key
Confirm the key hash exists in the database used by the AngleModules licensing installation and that the exact key is stored in WHMCS.
Configured key file is not readable
Replace placeholder text with an absolute PEM path and confirm ownership and file permissions.
Checkout URL is not returned
Confirm environment, Merchant ID, both Key IDs, PEM pairing and the sanitised gateway log.
Callback is rejected
Check the signed token, merchant match, invoice reference, amount, status and server time. Do not accept unsigned JSON as payment proof.
15. Security checklist
- Keep the merchant private key outside the public web root.
- Never upload private keys to tickets or screenshots.
- Use HTTPS for WHMCS and callbacks.
- Keep Debug Logging disabled after testing.
- Redact logs before sharing.
- Test UAT before enabling Production.
- Confirm the callback URL cannot be cached or replaced by a proxy error page.