# VPSRay WHMCS Reseller 1.0.1

Sell VPSRay VPS and dedicated servers from your own licensed WHMCS installation, under your own brand and monthly retail prices. Your WHMCS collects payment from your customers. VPSRay charges the connected reseller account's USD or USDT wallet for the initial order and for monthly wholesale renewals. End customers do not need a VPSRay account.

This is a **server provisioning module**. It is separate from the owner-only VPSRay WHMCS supplier bridge. Do not install the supplier bridge to resell VPSRay.

## Requirements

- A licensed WHMCS installation using its supported PHP 8.1+ environment, PHP cURL, HTTPS with a current CA trust store, and working WHMCS cron. Interfaces used are available in WHMCS 8.10+; run the controlled integration check below on your installed version before opening sales.
- A VPSRay account with a funded USD or USDT wallet, purchasing enabled and an API key. The API key requires: `catalog:read`, `services:read`, `services:write`, `services:credentials`, `invoices:read`, `orders:write`, `wallet:read`, `wallet:pay`.
- Exact public Plan ID, location and OS choices from the authenticated VPSRay API catalog. The plan and chosen configuration must support monthly billing. The module does not choose the cheapest variant or silently substitute another location/OS.

## Install and connect

1. Back up your WHMCS database. Upload the ZIP's `modules` and `includes` directories into the WHMCS installation root. Keep `README.md` for the administrator; no addon activation is needed.
2. In WHMCS **System Settings → Servers**, add a server of module type **VPSRay Reseller**. Set hostname `vpsray.com`. Paste the VPSRay API key into the server **Password** field, where WHMCS stores it encrypted. Keep it out of product descriptions, custom fields and client templates. Do not put your VPSRay account password here.
3. Use **Test Connection**. It checks authentication, scopes and the wallet read endpoint only. It creates no order, invoice, payment or wallet authorization.
4. Create a **VPS/Dedicated Server** product, select the server/group and module **VPSRay Reseller**, and configure **monthly recurring** customer billing. Set your own product name, description, welcome email, retail price and currency in WHMCS. Your retail price is independent of the VPSRay quote and is never changed by the module.
5. In Module Settings enter the exact public Plan ID, Location, Operating system, Wallet currency, Maximum initial cost, Maximum monthly cost and reseller Billing contact. Cost limits are integer minor units: `2000` means USD 20.00 or USDT 20.00. The initial limit includes setup fees. Review and tick **Monthly wallet renewal** to authorize monthly debits within that service's monthly limit, independently of your own WHMCS customer payments. A new order is blocked until this explicit authorization is enabled. To revoke an existing authorization, use **Stop monthly renewal**; unticking a product setting does not contact VPSRay.
6. Billing contact is your reseller/business information, as JSON. Do not copy end-customer billing records into this setting. Example with fictional details:

```json
{"firstName":"Alex","lastName":"Example","address":"100 Example Street","city":"Example City","state":"CA","postcode":"90000","country":"US","phone":""}
```

7. Enable automatic setup **after the first payment is received** in WHMCS. Request the customer's valid server hostname using the standard WHMCS Domain/Hostname field. Linux hostname labels allow 1–63 letters, numbers or hyphens; labels cannot start or end with a hyphen. Windows requires a single computer name with 1–15 characters and at least one letter. Reserved Windows device names are rejected before any order is saved. The module does not submit WHMCS's generated initial password. It obtains verified installed credentials after activation and stores Username, Password and Dedicated IP using WHMCS Service Properties. Configure your own branded server welcome email to show the service's verified login fields.
8. Keep the normal WHMCS cron running (typically every five minutes). The included global hook revisits up to five pending activations per pass and up to ten unconfirmed cancellation requests. Larger queues take additional passes. This is activation/cancellation recovery, not a continuous real-time worker or ongoing synchronization of delivered WHMCS statuses. The client server panel reads the current VPSRay status when opened.

## What the module does

- Gets the exact selected monthly configuration quote and checks both cost ceilings before creating an order.
- Saves the exact request and stable order key in a private WHMCS database journal **before** submitting it. Saves the VPSRay invoice and service references before paying. Retries preserve that same request and key; network failures never create a replacement service identity.
- Pays the initial VPSRay invoice once from the selected reseller wallet. Insufficient balance, expired keys, unknown outcomes or pending activation remain actionable errors/pending checks; they never mark the WHMCS service active.
- After VPSRay confirms activation, obtains and authorizes the exact monthly wallet terms, then retrieves the installed login credentials. WHMCS becomes Active and sends its welcome email only after confirmed activation, authorization and credential delivery.
- Shows a small own-brand client service panel with status and valid IP addresses. API keys, wallet balance, invoice costs and integration diagnostics stay out of that panel. VPSRay's underlying suppliers, supplier panels and supplier references are never included.
- Provides administrator commands **Check activation** and **Stop monthly renewal**. Stop renewal revokes wallet auto-pay and schedules cancellation at the end of the paid VPSRay term. It does not immediately destroy the server and does not refund paid time.
- The included `CancellationRequest` hook records cancellation intent and runs Stop monthly renewal; the cron recovers temporary failures. A paid pending activation is followed until renewal can be stopped. An unpaid initial order is never paid by the cancellation path; it remains recorded until that same invoice is resolved or expires. The platform marks an eligible expired initial order cancelled, and the next module check then completes cancellation. A closed invoice alone is not treated as proof of service cancellation. Review the integration state if cancellation cannot yet be confirmed.

## Monthly billing and nonpayment

VPSRay wallet auto-pay is the only wholesale renewal payer. There is deliberately no WHMCS `Renew` implementation and no extra debit when a WHMCS retail renewal invoice is paid. WHMCS retail invoice dates/prices remain unchanged; an early VPSRay wholesale renewal does not advance a retail due date.

Keep the reseller VPSRay wallet funded. Auto-pay is tied to the service's exact currency, monthly cycle and authorized amount. If that quote changes, the existing authorization must be reviewed in VPSRay. If funds are unavailable, VPSRay's overdue policy applies; remote enforcement depends on its scheduler and confirmed provider outcome. There is no automatic card fallback in this module.

**Customer nonpayment in your WHMCS and reseller-wallet nonpayment in VPSRay are separate.** This first module does not implement WHMCS SuspendAccount, UnsuspendAccount, immediate TerminateAccount, upgrades, rebuilds, console, or password resets. Do not advertise those module actions or rely on WHMCS automatic suspension/termination to stop VPSRay wholesale costs. Configure cancellation at end of the billing period and use Stop monthly renewal or the customer's cancellation-request flow before the next wholesale renewal. The reseller remains responsible for collecting retail invoices and stopping wholesale renewal when needed. Suspension alone does not establish that wholesale charges have stopped.

## Recovery and safe operation

The journal table is `mod_vpsrayreseller`. Back it up with WHMCS. It contains order identity, immutable request/contact snapshot, invoice/service references, cancellation intent and short leases; no API keys or server credentials. Restrict database access. Never delete the journal or clone it into a live staging installation: doing so can lose recovery identity or make two hosts operate the same production services. Disable cron and live keys in staging.

Activation checks verify the saved invoice ID, service ID, amount and currency. A confirmed paid invoice is never sent to the wallet payment endpoint again; an interrupted payment response is reconciled by reading that same invoice. HTTP success alone does not establish payment or activation. Stop renewal is confirmed only when the API reports wallet auto-pay disabled.

The reseller billing contact is validated before creating an immutable order snapshot. Supply single-line fields with at most 160 characters, a two-letter country code and an optional phone containing 7–15 digits. Only the documented contact fields are sent.

If an activation reports pending, wait for cron or use Check activation on the same WHMCS service. Do not create another WHMCS service, change the plan/hostname, or repeatedly click Create. Keys may be rotated for the same VPSRay account. Switching accounts for an existing service is blocked. Restoring the original exact configuration is required if product settings changed mid-order. If a price limit is too low, review the existing snapshot and deliberately adjust that limit; an existing request is never silently re-quoted.

If login details have not yet been verified, the server stays pending in WHMCS even if VPSRay has activated it. The existing paid server is checked again; no replacement is ordered. Module responses are generic and contain no raw upstream errors, tokens or passwords. Transport uses a fixed `https://vpsray.com/api/reseller/v1` origin, verified TLS, timeouts and no redirects.

## Controlled verification before selling

Test Connection verifies authentication/scopes, not live provisioning. In your own WHMCS test product, perform one intentional paid monthly purchase with sufficient reseller wallet balance. Verify one journal/invoice/service, one wallet debit, pending-to-active status, installed credentials and your own branded welcome email. Replay Create on that same service and confirm no second order or charge. Test a low-balance case without treating it as active. Confirm monthly VPSRay wallet renewal and the end-of-term cancellation independently. Automated PHP state-machine tests do not certify a live licensed WHMCS host or a real supplier lifecycle.

Official integration references:

- https://developers.whmcs.com/provisioning-modules/module-parameters
- https://developers.whmcs.com/provisioning-modules/service-properties
- https://developers.whmcs.com/provisioning-modules/core-module-functions
- https://developers.whmcs.com/api-reference/modulecreate
- https://developers.whmcs.com/api-reference/modulecustom
- https://developers.whmcs.com/hooks-reference/cron
- https://developers.whmcs.com/hooks-reference/service