# 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)

```env
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)

```env
BILLING_PROVIDER=internal
```

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

## Stripe (optional fallback)

```env
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.