Security Practices
OpenPay is built with security as a foundational principle. This guide covers key management, encryption, authentication, network security, and compliance considerations for running your payment infrastructure securely.
Minimum Security Checklist
API Key Management
Sandbox vs Production Keys
OpenPay supports full environment isolation through separate key prefixes. Sandbox keys start with sk_test_ (or op_test_) and never process real payments. Production keys start with sk_live_ (or op_live_) and handle live transactions.
Key Rotation Policy
Rotate API keys every 90 days as a security best practice. To rotate: generate a new key in the dashboard, update your application configurations, verify the new key works, then deactivate the old key. Never share keys across environments.
Environment Variables
All secrets must be stored in environment variables, never hardcoded. Each service has its own .env file that is gitignored. Use .env.example templates with placeholder values for documentation.
Encryption at Rest & In Transit
TLS/SSL (In Transit)
Traefik terminates TLS at the edge using automatic Let's Encrypt certificates. All external traffic is encrypted with TLS 1.3. Internal service-to-service communication runs over the Docker internal network (not exposed to the host), but can be configured with mTLS for additional security.
Database Encryption (At Rest)
PostgreSQL data is encrypted at rest using the host filesystem encryption (LUKS for Linux, BitLocker for Windows). Hyperswitch additionally encrypts sensitive fields (card BIN, last 4 digits) with AES-256 using the MASTER_ENC_KEY configuration.
Redis Encryption
Redis supports optional TLS encryption for connections. Enable by setting REDIS_TLS_ENABLED=true and providing the certificate path. Redis passwords are hashed using SHA-256 before storage.
Authentication & Authorization
API Authentication
All API requests to Hyperswitch require an api-key header. Keys are generated using cryptographically secure random bytes. The dashboard uses Kinde for user authentication with support for OAuth2, OIDC, and social login providers.
Role-Based Access Control (RBAC)
The dashboard supports three roles: Admin (full access), Developer (API keys, payments, webhooks), and Analyst (read-only, fraud cases, reports). Roles are enforced server-side through Kinde permissions and middleware guards.
Service-to-Service Authentication
Internal services (NATS, Tazama, NATS-KB Bridge) authenticate using JWT tokens or username/password credentials. Each service has its own credentials stored in its .env file. NATS supports token-based authentication for client connections.
Webhook Security
Signature Verification
All webhook events are signed using HMAC-SHA256. Your webhook endpoint must verify the signature before processing events to prevent forgery. The signing secret is configured per webhook endpoint.
HTTPS Enforcement
Webhook endpoints must use HTTPS. OpenPay will refuse to deliver events to HTTP URLs in production mode. For local testing, use a tool like ngrok
IP Allowlisting
Webhook events are sent from a predictable IP range. Configure your firewall to only accept webhook requests from these IPs. The current IP range is documented in the webhook settings page of your dashboard.
Network Security
Docker Network Isolation
Services are organized into Docker networks with strict isolation. The core-net bridge network connects all services, but sensitive services (PostgreSQL, Redis, NATS) only expose their ports within the Docker network — they are not accessible from the host.
Firewall Rules
Only expose ports 80 (HTTP → HTTPS redirect) and 443 (HTTPS) to the public internet. All other ports (3000, 8080, 8081, 8082, 5432, 6379, 4222) must be firewalled to internal access only.
Rate Limiting
Traefik applies rate limiting at the edge: 100 requests per second per IP by default. This prevents abuse and brute-force attacks. The rate limit can be adjusted per service in the Traefik configuration.
Data Privacy & PCI Compliance
PCI Compliance Architecture
OpenPay is designed for PCI DSS compliance when properly configured. Card data is tokenized by Hyperswitch and never stored in the merchant database. The merchant dashboard never collects raw card numbers — all card entry happens through Hyperswitch Elements (secure iframes).
Data Retention
Payment events are retained in NATS JetStream for 72 hours by default. Transaction records in PostgreSQL are kept indefinitely for accounting purposes, but sensitive card data (full PAN) is never stored — only the last 4 digits and BIN are retained for reference.
Logging & Audit Trails
All payment state transitions are logged with timestamps and actor information. Logs are emitted to stdout and can be aggregated using Docker logging drivers. In production, enable log aggregation (Loki, ELK, or CloudWatch) for centralized audit trails.
External Security Resources
PCI Security Standards Council
Official PCI DSS requirements and self-assessment questionnaires
Let's Encrypt Documentation
Free, automated TLS certificates for your production deployment
OWASP Top 10
Web application security risks and mitigation strategies
NATS Security Documentation
NATS authentication, authorization, and encryption options
PostgreSQL Security Guide
Database hardening, encryption, and access control