1.2 Overview of Hyperswitch Core Components
Before installing Hyperswitch and running your first payment, it’s important to understand the key components that make up the platform. The advantages of self-hosting control, transparency, and extensibility come from how these components are organized and how they work together. Each part of the system has a focused responsibility, and together they form a foundation that you can deploy, observe, and evolve within your own infrastructure. With this context in place, we now move into a high-level overview of the core components that power Hyperswitch.
At a bird’s-eye view, Hyperswitch consists of the following four layers:
Experience Layer
Core Backend Layer
Integrations/Connectors Layer
Developer Tools
1.2.1 Experience Layer
This layer encompasses what merchants and end customers interact with directly:
Control Center:
The Hyperswitch Control Center is the centralized operational dashboard that enables merchants, engineering teams, and payment operations to manage and observe their entire payments setup. It provides a unified interface to monitor transactions, analyze performance, configure payment processors, manage teams, and structure organizational complexity through the OMP (Organization, Merchant and Profile) hierarchy.
Core Capabilities:
Monitor Payments: Track real-time payment activity, inspect lifecycle events, and view detailed payment attempts.
Observe and Analyse Payment Analytics: Access dashboards for transaction success rates, trends, processor performance, and routing outcomes.
Manage Users and Access: Use role-based access controls to onboard team members and assign the right permissions.
Manage Connectors and Routing Rules: Configure payment processors, enable supported methods, and define routing and fallback behavior.
Manage Refunds and Disputes: Initiate and track refunds, and manage dispute and chargeback workflows where supported.
Design Organizational Complexity with OMP: Use the Organization → Merchant → Profile hierarchy to separate brands, geographies, or business units cleanly.
Repository: https://github.com/juspay/hyperswitch-control-center
Together, these capabilities give merchants a seamless, manageable interface for payments.
Unified SDK (Web, iOS, Android):
The Hyperswitch Unified SDK provides a consistent, secure, and customizable way to embed checkout experiences across Web, iOS, and Android applications. It abstracts the complexity of handling payment methods, encrypting sensitive data, and initiating payment flows giving developers a unified interface while ensuring customers experience a smooth, modern checkout across platforms.
Core Capabilities:
Payment Method Management: Support for cards, wallets, and alternative payment methods with consistent APIs across platforms.
Collect Payment Details Securely: Use PCI-compliant components to gather card details or wallet information without exposing sensitive data to your servers.
Initiate Payments for Processing: Create, confirm, or retry payments directly from the client, with built-in support for status updates and polling.
Payment Element Management: Render secure payment elements (card input, wallet buttons, method selectors) that integrate seamlessly into app UIs.
Customization and Theming: Configure styles, button shapes, sizes, colors, typography, and layout to match your brand and UX guidelines.
Cross-Platform Consistency: Provide customers with a unified and predictable payment experience on Web, iOS, and Android through shared design patterns.
Integration with Backend APIs: Communicate with the Hyperswitch backend for creating intents, confirming payments, handling redirects, and resolving 3DS flows.
Repositories:
Android SDK: https://github.com/juspay/hyperswitch-sdk-android
1.2.2 Core Backend Layer
The core backend server is the heart of Hyperswitch, responsible for receiving API requests, orchestrating payment flows, managing state, and interacting with both internal and external services. This layer brings together several foundational components, each with a distinct purpose: the Router orchestrates the end-to-end payment lifecycle, the Card Vault secures and manages sensitive payment data, the Scheduler handles asynchronous and deferred tasks, and the Decision Engine determines the optimal connector for each transaction.
The Router is the primary API server and the main orchestration engine of Hyperswitch. It exposes a comprehensive suite of REST APIs that allow merchants to create, confirm, update, and retrieve payments, initiate refunds, manage disputes, store customers and payment methods, and configure connectors. It also manages the Organization → Merchant → Profile (OMP) hierarchy. Once a request enters the system, the Router coordinates the entire payment lifecycle from authorization and capture to refunds and asynchronous updates while maintaining consistent state transitions and enforcing business rules. This component acts as the central decision-maker and workflow controller for all payment operations.
The Scheduler handles all asynchronous and deferred tasks required for reliable payment processing. Many workflows such as querying processors for updated payment statuses, retrying failed webhook deliveries, deleting expired cards, and issuing API key expiration notifications cannot be completed synchronously. The Scheduler manages these tasks using a Producer–Consumer model. The Producer monitors scheduled tasks in the database, retrieves them when they become due, batches them, and pushes the batches into a Redis queue. The Consumer then processes these batches, executing tasks promptly without blocking API requests. This model ensures resilience, orderly execution, and smooth handling of long-running or background workflows.
Repository: https://github.com/juspay/hyperswitch
The Card Vault is a PCI-compliant service responsible for securely storing and managing all sensitive payment information. This includes card numbers, network tokens, wallet credentials, and bank account details. By isolating sensitive data within the Vault, Hyperswitch minimizes PCI exposure for the rest of the system and enables secure tokenization, saved payment methods, recurring flows, and lifecycle management for payment credentials. The Vault ensures that all sensitive information remains encrypted both at rest and in transit, preserving security while supporting flexible payment experiences.
Repository: https://github.com/juspay/hyperswitch-card-vault
The Decision Engine is an external routing service that evaluates merchant-defined rules to determine the optimal connector for each payment. It supports static strategies, such as rule-based, cost-based, and volume-based routing, as well as dynamic approaches driven by processor performance data and machine-learning models. By selecting the best connector for every attempt, the Decision Engine improves success rates, lowers processing costs, and provides flexibility in multi-processor environments.
Repository: https://github.com/juspay/decision-engine
The Encryption Service, or Key Manager, manages encryption keys and protects sensitive data across the Hyperswitch platform. Card numbers, tokens, bank account details, and other payment information remain encrypted in transit and at rest, enforcing consistent cryptographic policies across all components and microservices. By centralizing encryption operations, it helps teams meet PCI requirements and keeps sensitive data secure throughout the entire payment lifecycle.
Repository: https://github.com/juspay/hyperswitch-encryption-service
1.2.3 Connectors / Integrations Layer
The Connectors Layer is responsible for integrating Hyperswitch with the broader payment ecosystem. It contains a wide variety of connector types such as payment processors, fraud engines, 3DS authentication providers, alternative payment methods, payout services, tax engines, and more. These connectors allow Hyperswitch to invoke external services as part of the payment flow without requiring merchants to build or maintain direct integrations themselves. Instead, merchants simply configure the desired processors and services in the Control Center, and Hyperswitch handles the orchestration during runtime.
All connectors are implemented and maintained within the main Hyperswitch repository:
https://github.com/juspay/hyperswitch
Connectors in Hyperswitch follow a consistent abstraction and error-handling model. This allows the Router to interact with different providers through a unified interface, normalize request and response formats, and execute routing, retries, and fallbacks transparently. As a result, adding or switching processors becomes a configuration change rather than an engineering project.
Unified Connector Service: Alongside the existing connector framework, Hyperswitch is evolving toward a dedicated Unified Connector Service (UCS) , a standalone and stateless service designed specifically for payment processor integrations. UCS provides a unified API layer for processors, allowing connector logic to be isolated, scaled independently, and reused across products. It enables more modular development, easier extension, and improved performance for processor-heavy workloads. UCS will eventually become the central integration layer for all payment processor connectors.
Repository: https://github.com/juspay/connector-service
1.2.4 Developer Tools Layer
The Developer Tools Layer provides everything required to deploy, operate, observe, and test a self-hosted Hyperswitch installation. It ensures that Hyperswitch is not just a payments application but a fully operable platform that can be run, monitored, and scaled with confidence in any environment.
Deployment Tools:
To simplify deploying the core components - Router, Card Vault, Scheduler, Decision Engine, Control Center etc., Hyperswitch offers Helm charts that package all services into a production-ready Kubernetes deployment. These charts, available in the hyperswitch-helm repository (https://github.com/juspay/hyperswitch-helm), allow teams to deploy Hyperswitch on locally managed clusters like Minikube or OrbStack, or on cloud-managed environments such as GKE, EKS, and AKS, with consistent configuration patterns across all environments.
For performance evaluation, Hyperswitch also provides a dedicated test suite in hyperswitch-suite (https://github.com/juspay/hyperswitch-suite). This suite includes load-testing tools that help teams benchmark their deployments, model high-traffic scenarios, and size their infrastructure appropriately before production rollout.
Observability and Monitoring Tools:
Hyperswitch includes a complete observability stack designed to give engineering and operations teams full visibility into their payments infrastructure. The system collects four kinds of telemetry metrics, logs, traces, and domain events each with its own tailored pipeline for collection, querying, storage, and visualization. These pipelines allow teams to understand system health, diagnose issues, and analyze payment behavior in both real time and historically. The stack leans on industry-standard tooling such as Prometheus, Loki, Tempo, Kafka, and ClickHouse, with OpenTelemetry powering collection for logs and traces.
Metrics - System Health and Performance: Hyperswitch emits a rich set of application and connector metrics, covering request counts, latencies, success rates, connector failures, retry patterns, scheduler activity, and more. These metrics are collected using the OpenTelemetry Metrics SDK, which employs a periodic reader to export data at fixed intervals.
From there, they are consumed by Prometheus, which acts as both the query layer and storage backend, maintaining a time-series database of all numeric telemetry. Prometheus stores raw metrics and supports alerting rules to detect anomalies such as rising error rates or unusual latency spikes. Visualization is provided through Grafana, where Hyperswitch ships with preconfigured dashboards offering insight into overall performance, processor reliability, scheduler operations, and system load. Metrics are essential because they allow teams to understand system behavior at a glance and quickly identify trends or regressions.
Logs - Application Visibility: Logs capture the most granular details of how Hyperswitch behaves at runtime, including connector interactions, API requests and responses, retries, errors, and the outcomes of asynchronous tasks. Hyperswitch produces structured JSON logs with configurable levels, making them easy to parse and filter.
These logs are collected using Promtail, which scrapes container logs and forwards them to Loki, the log aggregation system. Loki acts as both the querier and storage layer, indexing logs with labels for efficient searching. In Grafana, operators can filter logs by merchant, payment ID, connector, or error type, making it easy to reconstruct execution paths or investigate failures. Logs are critical because they provide contextual insight that neither metrics nor traces can fully capture.
Traces - End-to-End Payment Flow Insight: Distributed traces provide a visual timeline of how a request flows across Hyperswitch services. Traces capture spans for each segment of a payment flow including Router API handling, connector calls, scheduler operations, and asynchronous continuations.
Traces are collected by the OpenTelemetry Tracer, which uses a batch processor to export spans with configurable sampling rates. These spans are then routed to Grafana Tempo, which serves as the query layer and storage backend for distributed traces. Grafana visualizes traces through flame charts and dependency graphs, allowing teams to pinpoint slow connectors, expensive API paths, or bottlenecks in multi-step flows. Traces are essential for diagnosing latency issues and understanding the performance characteristics of complex workflows.
Events - Business and Lifecycle Analytics: Domain events capture meaningful business actions within Hyperswitch - payment state transitions, refund progress, connector outcomes, webhook events, and more. These events are streamed into Kafka, which provides dependable, ordered delivery suited for event-driven architectures. Kafka then forwards them to ClickHouse, a columnar analytical database built for high-performance ingestion and querying.
ClickHouse serves as the analytics backend for the Hyperswitch Control Center, enabling merchants and operators to explore historical payment behavior, understand trends, and investigate anomalies at a business and lifecycle level. Events fill the semantic gap between technical telemetry and business outcomes, making them essential for operational intelligence.
Last updated