Back to Self-HostingRoot
Hyperswitch
Monitoring
Kill Bill
Merchant Dashboard
Environment Variables
Complete reference for all environment variables across every service in the OpenPay stack.
Root .env
The main environment file at the project root. Shared across all Docker containers.
| Variable | Required | Description |
|---|---|---|
POSTGRES_PASSWORD | Required | Password for the PostgreSQL database |
REDIS_PASSWORD | Required | Password for the Redis cache |
HYPERSWITCH_API_KEY | Required | API key for Hyperswitch (generate once) |
PAYSTACK_SECRET_KEY | Required | Paystack secret key from dashboard.paystack.co |
PAYSTACK_PUBLIC_KEY | Required | Paystack public key from dashboard.paystack.co |
PAYSTACK_WEBHOOK_SECRET | Required | Webhook signing secret from Paystack dashboard |
KILLBILL_API_KEY | Optional | API key for Kill Bill admin (auto-generated if empty) |
KILLBILL_API_SECRET | Optional | API secret for Kill Bill admin |
Hyperswitch .env
| Variable | Required | Description |
|---|---|---|
DATABASE_HOST | Required | PostgreSQL host (default: postgres) |
DATABASE_PORT | Required | PostgreSQL port (default: 5432) |
DATABASE_NAME | Required | Database name (default: hyperswitch) |
DATABASE_USERNAME | Required | Database username |
DATABASE_PASSWORD | Required | Database password (must match root .env) |
REDIS_HOST | Required | Redis host (default: redis) |
REDIS_PORT | Required | Redis port (default: 6379) |
REDIS_PASSWORD | Required | Redis password |
NATS_URL | Required | NATS connection URL (default: nats://nats:4222) |
PAYSTACK_SECRET_KEY | Required | Paystack secret key |
API_KEY | Required | Hyperswitch API key for client auth |
EMAIL_ACTIVE_CLIENT | Optional | SMTP or SES (default: SMTP) |
EMAIL_SENDER_EMAIL | Optional | From: address for auth emails (must be on the verified domain) |
EMAIL_SMTP_HOST | Optional | Provider SMTP host (dev: mailhog / prod: smtp.resend.com, etc.) |
EMAIL_SMTP_PORT | Optional | SMTP port (1025 MailHog, 587 start_tls) |
EMAIL_SMTP_CONNECTION | Optional | plaintext (dev) or start_tls (prod) |
EMAIL_SMTP_TIMEOUT | Optional | Seconds before SMTP timeout (default 10) |
EMAIL_SMTP_USERNAME | Optional | Provider SMTP username/API key |
EMAIL_SMTP_PASSWORD | Optional | Provider SMTP password/API key |
HYPERSWITCH_DASHBOARD_URL | Optional | Public dashboard URL baked into email links |
HYPERSWITCH_PUBLIC_API_URL | Optional | Public router URL the Control Center calls |
HYPER_EMAIL_ENABLED | Optional | true = email-based team invites in Control Center |
Monitoring .env
| Variable | Required | Description |
|---|---|---|
GRAFANA_ADMIN_USER | Optional | Grafana login (default: admin) |
GRAFANA_ADMIN_PASSWORD | Optional | Grafana password (default: admin — change for production) |
Kill Bill .env
| Variable | Required | Description |
|---|---|---|
DATABASE_HOST | Required | PostgreSQL host |
DATABASE_NAME | Required | Database name (default: killbill) |
DATABASE_USERNAME | Required | Database username |
DATABASE_PASSWORD | Required | Database password |
KILLBILL_API_KEY | Required | Kill Bill API key |
KILLBILL_API_SECRET | Required | Kill Bill API secret |
KILLBILL_DEFAULT_USERNAME | Required | Default admin username (default: admin) |
KILLBILL_DEFAULT_PASSWORD | Required | Default admin password |
NATS_URL | Required | NATS connection URL |
Merchant Dashboard .env.local
Phase 3: the dashboard is sandbox/production mode-aware. Credentials are resolved per mode from the openpay_mode cookie (see src/lib/mode.ts). Per-mode pairs win; the legacy single-mode vars remain as a fallback.
| Variable | Required | Description |
|---|---|---|
KINDE_CLIENT_ID | Required | Kinde application client ID |
KINDE_CLIENT_SECRET | Required | Kinde application client secret |
KINDE_ISSUER_URL | Required | Kinde domain URL (e.g., https://your.kinde.com) |
KINDE_POST_LOGIN_REDIRECT_URL | Required | Redirect after login (default: http://localhost:3000/dashboard) |
KINDE_POST_LOGOUT_REDIRECT_URL | Required | Redirect after logout (default: http://localhost:3000) |
HYPERSWITCH_URL_TEST | Required | Sandbox router URL (default: http://localhost:8081) |
HYPERSWITCH_API_KEY_TEST | Required | Sandbox secret API key (e.g. snd_<key_id>-<secret>) |
NEXT_PUBLIC_OPENPAY_PUBLISHABLE_KEY_TEST | Optional | Sandbox publishable key used by the checkout page |
HYPERSWITCH_URL_LIVE | Optional | Live router URL (required only for production mode) |
HYPERSWITCH_API_KEY_LIVE | Optional | Live secret API key (e.g. prd_<key_id>-<secret>) |
NEXT_PUBLIC_OPENPAY_PUBLISHABLE_KEY_LIVE | Optional | Live publishable key used by the checkout page |
HYPERSWITCH_MERCHANT_ID_TEST | Optional | Sandbox merchant account id (default: default) |
HYPERSWITCH_MERCHANT_ID_LIVE | Optional | Live merchant account id (default: default) |
HYPERSWITCH_ADMIN_API_KEY | Optional | Router admin key (used to issue/revoke merchant API keys) |
NEXT_PUBLIC_OPENPAY_MODE | Optional | Fallback mode when no cookie/query: sandbox or production |
HYPERSWITCH_URL | Optional | Legacy fallback router URL (single-mode installs) |
HYPERSWITCH_API_KEY | Optional | Legacy fallback secret API key |
A production-mode request with no live credential configured fails fast (HyperswitchError, HTTP 503) rather than silently reusing the sandbox key. Deployed Vercel environments should map Production → _LIVE vars and Preview → _TEST vars.