diff --git a/docker-compose.env.example b/docker-compose.env.example
index 8e8ddf328..a81dc5429 100644
--- a/docker-compose.env.example
+++ b/docker-compose.env.example
@@ -60,6 +60,27 @@ LOG_LEVEL=info
 ENABLE_CLAMAV=true
 CLAMAV_REQUIRED=true
 
+# =============================================================================
+# PAYMENTS (HYPERSWITCH) - PRODUCTION
+# =============================================================================
+#
+# For real checkout in production, Hyperswitch MUST be enabled.
+# When HYPERSWITCH_ENABLED=false, orders complete without real payment (dev only).
+#
+# HYPERSWITCH_ENABLED=true
+# HYPERSWITCH_URL=http://hyperswitch:8080
+# HYPERSWITCH_API_KEY=your_api_key_from_control_center
+# HYPERSWITCH_WEBHOOK_SECRET=whsec_xxx
+# HYPERSWITCH_DB_USER=hyperswitch
+# HYPERSWITCH_DB_PASS=CHANGE_THIS_HYPERSWITCH_DB_PASSWORD
+# HYPERSWITCH_DB_NAME=hyperswitch
+# CHECKOUT_SUCCESS_URL=https://yourdomain.com/purchases
+#
+# Frontend (build-time): VITE_HYPERSWITCH_PUBLISHABLE_KEY=pk_xxx
+#
+# See docs/PAYMENTS_SETUP.md for full setup.
+# =============================================================================
+
 # =============================================================================
 # FRONTEND CONFIGURATION (PRODUCTION)
 # =============================================================================
diff --git a/docs/PAYMENTS_SETUP.md b/docs/PAYMENTS_SETUP.md
index bb84804c3..2545b5244 100644
--- a/docs/PAYMENTS_SETUP.md
+++ b/docs/PAYMENTS_SETUP.md
@@ -110,16 +110,20 @@ When `HYPERSWITCH_ENABLED=false` or Hyperswitch is not configured:
 
 - Orders are completed immediately (simulated payment)
 - Licenses are created without real payment
-- Useful for local development without Hyperswitch
+- **Useful for local development only** — never use in production
 
 ## 9. Production Checklist
 
+**CRITICAL**: Real payments require `HYPERSWITCH_ENABLED=true`. With `false`, orders complete without payment (dev/simulated only).
+
+- [ ] Set `HYPERSWITCH_ENABLED=true` in production
 - [ ] Use Mollie live API key
 - [ ] Use Hyperswitch production keys (`pk_prd_`, `sk_prd_`)
 - [ ] Set `CHECKOUT_SUCCESS_URL` to production domain
 - [ ] Configure webhook with production URL
 - [ ] Verify webhook signature in handler (Phase 7)
 - [ ] Ensure `HYPERSWITCH_WEBHOOK_SECRET` is set and kept secret
+- [ ] Set `VITE_HYPERSWITCH_PUBLISHABLE_KEY` at build time for frontend
 
 ## Troubleshooting