# Coinvay for WHMCS · 1.2.0

## Install
1. On staging, back up WHMCS and its database. Use WHMCS 8.x on PHP 8.1+ with cURL, MySQL/MariaDB and HTTPS. Use a WHMCS release that supports your PHP version. MySQL GET_LOCK/RELEASE_LOCK must work.
2. Extract the ZIP and upload **modules/** and **includes/** into the WHMCS root. This adds a gateway, callback, cron hook and private helper files; it does not replace WHMCS core.
3. WHMCS → System Settings → Payment Gateways → All Payment Gateways → Coinvay. Opening configuration creates the `mod_coinvay` invoice-mapping table. Set origin `https://coinvay.com` and your merchant API key. Supported invoice currencies are sent to Coinvay for USD pricing. Disable WHMCS gateway currency conversion to prevent double conversion. The module upgrades its mapping table with original currency and locked USD total; old mappings default to USD. Confirmed payments are credited in the original WHMCS invoice currency.
4. Choose **Connect to Coinvay** to authorize and save store credentials automatically, or confirm **Manual setup** with your saved key. Add your business name and logo. This registers a store-specific webhook/signing secret; signed notifications require an eligible plan. Existing non-store/global callbacks remain unchanged.
5. Ensure WHMCS system cron runs. The AfterCronJob hook reconciles 20 unapplied invoices per pass with a rotating cursor under templates_c (must be writable). Its frequency follows your WHMCS cron, not browser visits.
6. Generate an unpaid USD invoice, assign Coinvay, and click Pay with crypto. The amount is the server-provided outstanding balance. After payment, return to the invoice. Confirmation records one transaction `coinvay:inv_…` through WHMCS's payment function.

Amounts/balances must still match when confirmation arrives. A credit, partial payment, currency, payment-method or status change requires manual review; the callback never silently over-credits a changed invoice. Do not allow other payment workflows to edit an invoice while its crypto checkout is in use. The module's lock serializes its own workers, not unrelated WHMCS extensions. Existing accounting rows recover a crash before its applied flag; use normal WHMCS failed-provisioning recovery if a service hook fails.

## Staging acceptance
Try repeated invoice-page loads, invalid signatures, wrong order/amount, late payment, changed balance/currency, cancelled invoice, concurrent callback/cron and a provider outage. Confirm one accounting entry and correct service provisioning. Retry a duplicate webhook; it must not credit twice. Verify store-specific tax, credit and partial-payment settings. No real WHMCS tenant has been tested in this development environment.

Recurring renewals create normal WHMCS invoices; each invoice is paid separately. Automatic token debits and automatic refunds are not implemented. Disable new checkout and reconcile invoices before removing files. Preserve `mod_coinvay` and accounting history for reconciliation.


## Branding

The updated Coinvay logo assets and usage instructions are included in [BRANDING.md](BRANDING.md). Use SVG on supported web surfaces and PNG for native/platform restrictions.


## Manual or automatic account connection · 1.2.0

Use **Connect to Coinvay** to sign in and authorize this store, or retain manual API-key setup. This release adds separate checkout business name/logo and per-store signed webhooks without changing other stores. Read **CONNECT.md**, included in this package, for exact controls, environment variables, administrator-session integration, encryption/backups, permissions and staging checks. Custom app kits require your existing administrator authentication; Shopify remains subject to platform approval.