Swapspay for WHMCS
WHMCS 8.x / 9.x; PHP 7.4+ with cURL and MySQL
## Installation
1. Back up WHMCS. Extract the ZIP and merge its modules and includes directories into your WHMCS root. Do not replace your entire directories.
2. Activate Swapspay Crypto Payments in Apps & Integrations / Payment Gateways. Set your dedicated live API key and webhook signing secret.
3. Add the webhook at https://YOUR-WHMCS/modules/gateways/callback/swapspay.php. Include any WHMCS subdirectory in this URL.
4. Confirm your normal WHMCS cron runs every five minutes. The included AfterCronJob hook reconciles pending invoices even when a webhook is delayed.
5. Select Swapspay on an unpaid invoice. The payment button shows its unique Payment ID and opens hosted checkout. The invoice must still have the original balance and currency when payment confirms.
The WHMCS database user needs CREATE permission for the module's payment mapping table, created on first use. Each invoice receives one payment request; changed balances and partial payments require review. This gateway does not auto-charge subscription renewals; customers pay each renewal invoice themselves.
Before enabling payments
Use HTTPS and a dedicated live API key created in Swapspay → API keys. The website attached to that key must be your store hostname. Create a webhook in Swapspay → Webhooks using the callback URL below, then copy its signing secret into the plugin. Send a connection-test event and verify delivery in Swapspay.
Every payment gets a separate Swapspay Payment ID. The order reference stays your order reference. The customer uses the existing hosted checkout, with a fresh deposit address and automatic detection; there is no TXID form. USDC/USDT use 1 token per USD, with other invoice currencies converted by Swapspay. Asset availability comes from the hosted checkout, so plugins do not hard-code a coin list.
Payment handling
Only an authenticated API response with live mode, matching Payment ID, reference, currency and amount, and status paid can complete the order. A webhook is a wake-up signal, not proof of payment. Repeated requests reuse the same payment; duplicate callbacks do not credit the order twice. Pending, confirming, underpaid and expired payments are not marked paid. Cancelled or changed orders require manual review. If the invoice changes after a payment is created, review it rather than reusing its checkout for a different amount. Do not rotate keys with pending requests until reconciled; each store should use its own key.
No automatic refunds, conversion, recurring debits or subscription mandates are provided. Recurring invoices can be paid individually where the platform generates a new invoice. Supported currencies are those available in Swapspay; invoices must resolve to positive amounts with at most two nonzero decimal places. There is no platform surcharge added by these plugins.
Release validation
Version 1.0.0. PHP syntax and payment-contract checks run against these packages. A real payment has not been completed on a WHMCS, PrestaShop or OpenCart store for this release. Before customer use, test your platform version and theme: create an invoice with cents, retry creation, complete a small payment, replay its webhook, then verify that wrong signatures, changed totals and unconfirmed payments cannot fulfil orders. Check mail, tax, shipping and stock behaviour in your store. Keep your store backup before installation.
Troubleshooting
If an order stays pending, check webhook delivery logs in Swapspay, then your store's payment log. Confirm that the API key and webhook belong to the same website. Retry failed webhooks from Swapspay. Quote-expired, underpaid, late and changed-order payments require merchant review; do not fulfil from a customer screenshot or checkout return. Backup polling checks the oldest unchecked pending rows first, up to 20 per run for seven days. After seven days, use webhook retries and manual review. Uninstalling preserves financial records. Disable the payment method before removing files and finish pending orders first.