HexaHost-GameCloud/docs/billing/providers.md

Billing providers

GameCloud supports three billing modes via BILLING_PROVIDER:

Provider	Use case	Credit wallet
internal	Dev / free tier	Required for start
whmcs	Production default	Bypassed — WHMCS bills customers
stripe	Optional fallback without WHMCS	Bypassed — extend webhook handler

WHMCS (recommended)

BILLING_PROVIDER=whmcs
WHMCS_INTEGRATION_ID=your-integration-id
WHMCS_API_SECRET=your-secret

Commercial lifecycle (orders, invoices, suspend, usage metrics) runs entirely in WHMCS. GameCloud enforces billingSuspendedAt from WHMCS API calls.

Internal (development)

BILLING_PROVIDER=internal

Uses the credit wallet and usage metering from Phase 7. Suitable for local development and standalone free tier.

Stripe (optional fallback)

BILLING_PROVIDER=stripe
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

Webhook endpoint: POST /api/v1/webhooks/stripe

When BILLING_PROVIDER is not stripe, webhooks return { received: true, mode: 'ignored' } without side effects.

The current implementation verifies signatures and logs events idempotently. Extend StripeWebhookService to map Stripe customers to GameCloud users if you deploy without WHMCS.

Do not enable Stripe and WHMCS billing simultaneously — choose one commercial system of record.