Hyperswitch Admin Guide

Audience: platform engineers, SREs, security teams, and architects who deploy, configure, secure, and operate Hyperswitch in production. This guide covers the system architecture, the complete configuration surface, the security model, day-2 operations, and the internals you need to run a payments platform reliably. Everything here is derived from the source at the referenced commit.

1. Executive Summary

Hyperswitch is an open-source (Apache 2.0) payment orchestration platform built in Rust by Juspay. The application server in this repository accepts payment API requests, applies routing and decisioning, talks to 100+ payment processors through a unified connector layer, and persists state to PostgreSQL with a Redis-backed write-through cache. It is operated alongside a PCI card vault, an encryption/key-management service, a merchant dashboard (Control Center), and client SDKs.

What you deploy is up to three Rust binaries plus their data dependencies:

Core data dependencies: PostgreSQL (primary + optional read replica) and Redis. Optional services: card vault, encryption/key-manager service, an analytics pipeline (Kafka + ClickHouse + OpenSearch), a monitoring stack (Grafana/Loki/Tempo/Prometheus/OpenTelemetry), email (AWS SES or SMTP), and the Superposition dynamic-config service.

Important

Hyperswitch is compile-time configurable. Major capabilities are Cargo feature flags (v1/v2, olap/oltp, payouts, frm, email, kv, dynamic_routing, …). The official Docker images are built with a standard feature set; if you build your own binaries, the feature flags you choose determine which endpoints and subsystems exist. This is the single most important fact to internalize before operating Hyperswitch.

2. Architecture

2.1 Request and data flow

                         ┌──────────────────────────────────────────┐
   Merchant server  ───► │              router (actix-web)          │
   Checkout SDK     ───► │   /payments /refunds /customers /routing │
   Control Center   ───► │   /admin /webhooks  ... (olap + oltp)    │
                         └───────────────┬──────────────────────────┘
                                         │
            ┌────────────────────────────┼───────────────────────────────┐
            ▼                            ▼                                ▼
   ┌─────────────────┐        ┌───────────────────┐          ┌────────────────────┐
   │   PostgreSQL    │◄──────►│       Redis        │          │   Payment          │
   │ (master+replica)│        │  cache + streams   │          │   connectors       │
   └────────▲────────┘        └─────────┬──────────┘          │ (Stripe/Adyen/...) │
            │                           │                     └────────────────────┘
            │   drains SQL ops          │  enqueues tasks
   ┌────────┴────────┐         ┌────────┴─────────┐
   │     drainer     │         │    scheduler     │
   │ Redis stream→DB │         │ producer+consumer│
   └─────────────────┘         └──────────────────┘

   Side services: card vault (PCI), encryption/key-manager (KMS),
   analytics (Kafka→ClickHouse→OpenSearch), monitoring (Grafana/OTel),
   email (SES/SMTP), Superposition (dynamic config).

2.2 The KV (key-value) performance path

Hyperswitch can operate database writes in two modes per merchant:

• Direct SQL — the router writes straight to PostgreSQL.
• KV (write-through) — the router writes to a Redis stream (DRAINER_STREAM, partitioned num_partitions = 64) and serves reads from the Redis cache. The drainer asynchronously reads those streams and applies the SQL to PostgreSQL. This decouples request latency from database write latency at high throughput.

The KV mode is gated by the kv/full_kv configuration and the per-merchant use_kv flag. When you run KV, the drainer must be running or buffered writes will not reach the database.

Warning

In KV mode the drainer is on the critical durability path. If the drainer stops, Redis stream entries accumulate and database state falls behind. Monitor drainer liveness and Redis stream depth.

2.3 The scheduler / process tracker

Deferred work (delayed payment sync, retries, webhook delivery retries, mandate/scheduler jobs, recovery workflows) is enqueued into a process tracker and executed by the scheduler:

• The producer scans for due tasks and pushes batches (batch_size = 200) into a Redis queue under a producer lock.
• The consumer (consumer_group = "SCHEDULER_GROUP") pulls and executes them.

Both share a loop_interval (default 5000 ms) and a graceful shutdown interval. The scheduler also exposes a small health server (scheduler.server, default port 3000).

2.4 The connector abstraction

Every payment processor is implemented against a common set of traits (in hyperswitch_interfaces) and lives in hyperswitch_connectors / the connector modules. The router builds a connector-agnostic domain request, the connector implementation transforms it to and from the processor's wire format, and routing selects which connector handles a given transaction. This is what lets one API span 100+ processors.

2.5 The routing / decision engine (Euclid)

Routing rules are expressed in an internal rule engine (the euclid crate and its constraint-graph helpers hyperswitch_constraint_graph / kgraph_utils). It evaluates static rules (priority, volume split) and, with the dynamic_routing feature, success-rate and elimination strategies. Decision-manager configuration (3DS rules, surcharge) is managed through the /routing/decision endpoints.

2.6 Multitenancy

The server is multi-tenant. Each tenant has its own storage, accounts store, and (for analytics) its own pool, resolved per request from the multitenancy configuration. A global store holds cross-tenant tables (users, tenants). Tenant context flows through SessionState/AppState and into downstream service and gRPC headers.

2.7 Crate map

The workspace contains ~40 crates. Document and reason about them by layer, not individually:

Note

The clap-based binaries you may notice (config_importer, hsdev, the drainer/scheduler settings parsers, test_utils/newman_runner) are operations and development tools, not a user-facing CLI. Hyperswitch is operated through its config files and HTTP API, not a command-line surface.

3. System Requirements

4. Configuration Mastery

4.1 How configuration is loaded

Hyperswitch is configured with TOML files. The reference file is config/config.example.toml, which enumerates every available option with inline comments and defaults — treat it as the canonical configuration dictionary. Deployments use environment-specific files:

Important

The drainer and scheduler validate their configuration on startup and panic on invalid config (conf.validate()), failing fast rather than running misconfigured. Validate config changes in a non-production environment first.

4.2 Core sections

The following are the operationally critical sections. All defaults below are from config.example.toml.

[server] — HTTP server

[server.tls] enables HTTPS directly (port = 8081, private_key, certificate). In most deployments TLS is terminated at a load balancer instead.

[master_database] / [replica_database] — PostgreSQL

The replica is used for read traffic; point it at a read replica in production.

[redis] — cache and streams

Key options include host/port (127.0.0.1/6379), pool_size (5), default_ttl (300 s), default_hash_ttl (900 s), reconnect_max_attempts (5), default_command_timeout (30 s), max_in_flight_commands (5000), and max_failure_threshold_seconds (5 — the maximum time Redis may be unreachable before the server shuts down). Set use_legacy_version = true only for Redis < 6 / RESPv2. For clustered Redis use the clustered_redis deployment profile.

[secrets] — encryption and auth secrets

Caution

The example values (sample_key, test_admin, secret) are placeholders. Never run any non-local environment with example secrets. In production, source these through KMS rather than plaintext config.

[locker] — card vault

Warning

mock_locker = true stores card data in your application Postgres and is not PCI-compliant. For any real card data, run the dedicated hyperswitch-card-vault service and set mock_locker = false with a real host.

[key_manager] — encryption service

url (default http://localhost:5000) points at the encryption/key-management service. use_legacy_key_store_decryption controls upgrade compatibility — set false for new deployments, true only when upgrading from older versions. mTLS to the key manager is available with the keymanager_mtls build feature (cert, ca).

[scheduler] and [drainer]

The scheduler config defines the stream names, loop_interval (5000 ms), producer batch_size (200), consumer group, and the scheduler health server ([scheduler.server], port 3000). The drainer config defines stream_name (DRAINER_STREAM), num_partitions (64), max_read_count (100), and loop/shutdown intervals.

[api_keys], [eph_key], [webhooks], [refund], [cors], [user]

[connectors] and [pm_filters.*]

The [connectors] section sets the base URL for every processor (e.g. adyen.base_url, stripe.base_url, aci.base_url). These are not optional — an empty/invalid base URL makes requests to that connector fail. [pm_filters.<connector>] restricts which payment methods a connector offers by currency and country:

[pm_filters.stripe]
paypal = { currency = "USD,INR", country = "US" }

[log] and [log.telemetry]

Logging goes to file ([log.file], default off) and/or console ([log.console], default on). Levels: TRACE/DEBUG/INFO/WARN/ERROR/OFF. filtering_directive sets per-crate levels (e.g. WARN,router=INFO,reqwest=INFO). [log.telemetry] configures OpenTelemetry traces/metrics export (otel_exporter_otlp_endpoint default http://localhost:4317, sampling_rate 0.1, optional AWS X-Ray generator).

[email]

Only active with the email feature. Selects an active client (SES or SMTP), the sender address, and SES role configuration. The local Docker setup uses Mailhog for testing.

Analytics, forex, Superposition

[analytics] selects the analytics source (clickhouse) and [events] the event sink (kafka); enable them in development.toml/docker_compose.toml for the OLAP profile. [forex_api] holds the currency-conversion API keys and cache TTLs. Superposition provides dynamic, hot-reloadable configuration via its client.

5. Security

Payments software is a high-value target. Hyperswitch's security posture rests on layered key management, PII masking, a dedicated card vault, and explicit authentication tiers.

5.1 Authentication & authorization tiers

Optionally, merchant_id_auth_enabled requires an x-merchant-id header on payment endpoints, and the partial-auth build feature adds checksum-based key authentication.

5.2 Key management and encryption

• A master encryption key (secrets.master_enc_key, 32 bytes) encrypts each merchant's data-encryption key (envelope encryption).
• In production, secrets and keys are resolved through the encryption/key-manager service ([key_manager]), not plaintext config. Database passwords can be supplied as base64 KMS-encrypted values.
• mTLS to the key manager is available (keymanager_mtls).

5.3 Cardholder data and PCI scope

• Card data belongs in the card vault (hyperswitch-card-vault), a separate PCI-scoped service. Set locker.mock_locker = false and a real locker.host in production.
• The masking crate wraps PII/secret values so they are redacted in logs and debug output; the cards crate handles card masking and validation.
• The recommended integration keeps raw card data off your servers entirely by collecting it through the checkout SDK (client-side tokenization).

Caution

The biggest self-hosting security mistakes are: (1) running with mock_locker = true and real cards, (2) shipping example secrets, and (3) exposing the admin API key. Eliminate all three before going live.

5.4 Transport, CORS, and network

• Enable TLS at the edge (load balancer) or directly via [server.tls].
• Restrict [cors].origins to your known front ends; avoid wildcard_origin = true.
• Use the [proxy] settings to route outbound connector traffic through an egress proxy, with bypass_proxy_hosts for internal hosts.
• Verify outgoing-webhook signatures on your receiver, and verify the HMAC signature on payment redirect URLs using the profile's payment_response_hash_key.

5.5 Reporting vulnerabilities

Per the project's security policy, report vulnerabilities privately via GitHub Security Advisories on the repository or by email to [email removed] — never via public issues.

6. Operations

6.1 Running the services

Production runs the three binaries as separate workloads (the official images are hyperswitch-router, hyperswitch-producer, hyperswitch-consumer, hyperswitch-drainer, published under docker.juspay.io/juspaydotin/…):

For Kubernetes, use hyperswitch-helm; for a full provisioned stack, hyperswitch-suite (Terraform).

6.2 Database migrations

The schema is managed by Diesel migrations in migrations/ (and v2_migrations/ / v2_compatible_migrations/ for the v2 schema). In Docker Compose a migration-runner service applies them before the server starts. Apply migrations as a deploy step and ensure they complete before routing traffic to a new version.

Important

Database-schema, API-contract, and configuration changes are tracked explicitly in the project (the M-database-changes, M-api-contract-changes, M-configuration-changes labels). Treat any release carrying these as requiring a coordinated migration + config rollout.

6.3 Health checks

Wire /health to liveness probes and /health/ready to readiness probes so traffic only reaches replicas with healthy dependencies. The scheduler exposes its own health server on scheduler.server.port (3000).

6.4 Observability

• Logs: console (JSON via log_format = "json") and/or file, with per-crate filtering directives.
• Metrics & traces: OpenTelemetry export ([log.telemetry]) to an OTLP endpoint; optional AWS X-Ray. The monitoring Docker profile bundles Grafana, Loki, Tempo, Prometheus, and an OTel collector.
• Background metrics: collected on an interval (bg_metrics_collection_interval_in_secs, 15 s).
• Analytics: with the OLAP profile, events flow Kafka → ClickHouse, queryable via OpenSearch dashboards; Hyperswitch's own dashboards surface payment analytics.

6.5 Capacity and tuning levers

6.6 Backup, DR, and rollback

• State of record is PostgreSQL — back it up (and the card vault's storage) with point-in-time recovery. Redis is a cache/queue; in KV mode, drain it fully before any maintenance that could lose stream data.
• Rollback a release by deploying the previous image; do not run a newer schema against an older binary. Because migrations are forward-oriented, plan rollbacks at the application layer and keep migrations backward-compatible across one release where possible.

7. Troubleshooting (Operational)

Symptom: server exits shortly after start with a config error

Cause: Invalid configuration — the drainer/scheduler validate() panics on bad config; the router fails to construct required clients (encryption, store). Resolution: Check the startup logs for the specific section. Validate the active TOML against config.example.toml; confirm DB/Redis/key-manager reachability.

Symptom: Redis streams growing, DB state lagging

Cause: KV mode is on but the drainer is down or under-provisioned. Resolution: Restart/scale the drainer; verify it can reach Redis and PostgreSQL. Monitor stream depth as a first-class alert.

Symptom: Failed to fetch currency exchange rate / HE_00 / Could not acquire the lock for cache entry

Cause: Stale forex cache lock in Redis after enabling currency conversion. Resolution: redis-cli del "{forex_cache}_lock" and restart the app. Ensure valid [forex_api] keys.

Symptom: connector calls fail immediately

Cause: Missing/invalid [connectors].<connector>.base_url or bad credentials. Resolution: Set the correct base URL (sandbox vs. live) and re-enter credentials in the Control Center / via the connector-account API.

Symptom: requires_customer_action payments never complete

Cause: Customers cannot reach the authentication redirect, or return_url is unreachable. Resolution: Ensure the redirect URL from confirm is presented and return_url is publicly reachable; verify the redirect HMAC.

Symptom: Redis unreachable causes the server to shut down

Cause: Redis was down longer than redis.max_failure_threshold_seconds (min 5 s). Resolution: Restore Redis; the server self-terminates by design to avoid serving in an inconsistent state. Run Redis with HA (clustered profile) to avoid single-node outages.

8. Quick Reference

8.1 Default ports

8.2 Docker Compose profiles

8.3 Feature flags that change behavior

8.4 Config files

8.5 Key config sections at a glance

[server] · [server.tls] · [proxy] · [key_manager] · [master_database] · [replica_database] · [redis] · [secrets] · [locker] · [api_keys] · [eph_key] · [webhooks] · [refund] · [cors] · [user] · [merchant_id_auth] · [connectors] · [pm_filters.*] · [scheduler] · [drainer] · [log.*] · [email] · [forex_api] · [analytics] / [events].