# Billing, Invoices & Payments

How billing data is shown, refreshed, and kept accurate.

## Data Sources

- WHMCS is the billing system of record for clients, invoices, payment methods, gateways, and subscriptions.
- The portal does not store payment details; it only reads payment methods already saved in WHMCS.

## Invoices

- Retrieval: invoice lists and details are pulled from WHMCS for the mapped client ID.
- Caching: lists cached 90s; single invoice cached 5m. WHMCS webhooks and write operations clear these caches to keep totals current.
- Paying invoices: the portal generates a WHMCS SSO link for the specific invoice so customers pay directly in WHMCS without re-entering credentials.

## Payment Methods & Gateways

- Payment methods are stored in WHMCS. Before an order is accepted we check that at least one method exists.
- Caching: payment methods cached 15m per user; payment gateway list cached 1h. Caches are cleared after changes or on webhook-driven invalidations.

## Address & Profile in Billing

- Billing address and contact fields shown in the portal are pulled from WHMCS and treated as authoritative.
- When customers edit their profile/address, the portal writes the change to WHMCS and clears the relevant cache so invoices immediately reflect the new address.

## If something goes wrong

- WHMCS unavailable: we show a friendly “billing system unavailable, please try again” and avoid showing partial data.
- Payment method missing: checkout/fulfillment stops and tells the user to add a method; Salesforce is updated with a clear error code.
- Invoice not found or access denied: we return “invoice not found” without leaking other user data.