# WHMCS integration - ModuleCrafter WA v4

There are two different WHMCS modules.

## 1. Seller provisioning module

Install:

```text
modules/servers/modulecrafterwa/
```

Use this in the WHMCS where you sell ModuleCrafter WA plans.

Supported lifecycle actions:

- CreateAccount
- SuspendAccount
- UnsuspendAccount
- TerminateAccount
- Renew
- ChangePackage
- ChangePassword / Reset Gateway Password
- ServiceSingleSignOn
- service status and current usage

Product mapping example:

| Product | Price | Plan code |
|---|---:|---|
| 500 Messages every month | $2/mo | `wa500` |
| 1,000 Messages every month | $5/mo | `wa1000` |
| Unlimited Messages | $10/mo | `wa_unlimited` |

The module needs Gateway URL, `PROVISIONING_SECRET`, and the gateway plan code.

### Password reset from WHMCS admin

Set/save the desired WHMCS service Password, then execute **Reset Gateway Password** (or the normal module password-change action). v4 calls:

```text
POST /provisioning/v4/services/<service-id>/password
```

The gateway bcrypt-hashes the new password and revokes prior dashboard and one-time SSO sessions.

### Customer dashboard SSO

The product view can expose **Login to WhatsApp Dashboard**. WHMCS requests a short-lived one-use login URL. Redirects are limited to the configured gateway origin.

### Provisioning authentication

v4 uses timestamp + one-time nonce + HMAC-SHA256:

```text
X-MC-Timestamp
X-MC-Nonce
X-MC-Signature
```

Signature input:

```text
timestamp + "." + nonce + "." + exactJsonBody
```

The provisioning secret belongs only in your seller WHMCS and gateway `.env`.

## 2. Customer WHMCS Sender addon

Install:

```text
modules/addons/modulecrafterwa_sender/
```

A gateway customer creates a restricted **WHMCS Sender** token from the gateway and enters only:

- Gateway URL
- WHMCS Sender Token
- optional Channel ID
- notification/attachment preferences

There is intentionally **no Default Country Code** setting.

### Worldwide client phone handling

For every live WHMCS notification the addon reads:

```text
tblclients.phonenumber
tblclients.country
```

`country` is the client's two-letter WHMCS country code. The addon passes both fields to ModuleCrafter WA and the gateway normalizes the phone with worldwide numbering metadata.

Examples:

```text
US client: (213) 373-4253 + country US -> +12133734253
Nigeria client: 0803 123 4567 + country NG -> +2348031234567
Bangladesh client: 01712 345678 + country BD -> +8801712345678
UK client: 020 7946 0958 + country GB -> +442079460958
```

If a client already stores `+` international format, that number is used directly. This allows one WHMCS installation to serve clients from many countries at the same time.

A manually typed **Send Test Message** has no WHMCS client record/country context, so use international `+` format for that test.

### Test Connection and Test Message

The addon page includes:

- **Test Connection** - validates URL/token, returns gateway version, usage and channels.
- **Send Test Message** - sends through the exact v4 sender endpoint used by hooks. Final delivery/failure is visible in Gateway **Messages** and **Logs**.

### Notifications

Supported events:

- invoice created
- invoice paid
- invoice unpaid
- payment reminder/overdue
- new order
- order paid
- service activated
- service suspended
- service unsuspended
- service terminated

### Invoice PDF

When **Attach Invoice PDF** is enabled, WHMCS generates the invoice PDF in memory. The addon transfers it as private base64 document data to `/api/v4/whmcs/send`. The gateway validates size/MIME, stores it privately only while queued/sending, and removes the temporary file afterward.

The integration does not publish the invoice PDF as a public URL.

### Diagnostics

Sender calls use WHMCS `logModuleCall` with the token marked as sensitive/redacted. The gateway additionally records sanitized API request diagnostics and final failed message reasons under **Logs**.

Official Meta Cloud API channels still follow Meta's template, consent, quality and throughput rules.