1. Project Overview & Quickstart (juspay/hyperswitch)
Composable Open-Source Payments Infrastructure
π Table of Contents
- What Can I Do with Hyperswitch?
- Quickstart (Local Setup)
- Cloud Deployment
- Hosted Sandbox (No Setup Required)
- Why Hyperswitch?
- Architectural Overview
- Our Vision
- Community & Contributions
- Feature Requests & Bugs
- Versioning
- License
- Team Behind Hyperswitch
What Can I Do with Hyperswitch?
Hyperswitch offers a modular, open-source payments infrastructure designed for flexibility and control. Apart from our Payment Suite offering, this solution allows businesses to pick and integrate only the modules they need on top of their existing payment stack β without unnecessary complexity or vendor lock-in.
Each module is independent and purpose-built to optimize different aspects of payment processing.
Learn More About The Payment Modules
Cost Observability
Advanced observability tools to audit, monitor, and optimize your payment costs. Detect hidden fees, downgrades, and penalties with self-serve dashboards and actionable insights.
Read moreRevenue Recovery
Combat passive churn with intelligent retry strategies tuned by card bin, region, method, and more. Offers fine-grained control over retry algorithms, penalty budgets, and recovery transparency.
Read moreVault
A PCI-compliant vault service to store cards, tokens, wallets, and bank credentials. Provides a unified, secure, and reusable store of customer-linked payment methods. Also supports bring-your-own-vault to connect existing providers including VGS and TokenEx without re-tokenizing or migrating stored cards.
Read moreIntelligent Routing
Route each transaction across Stripe, Adyen, Braintree, Worldpay, Checkout.com, and 120+ others to the PSP with the highest predicted auth rate. Reduce retries, avoid downtime, and minimize latency while maximizing first attempt success.
Read moreReconciliation
Automate 2-way and 3-way reconciliation with backdated support, staggered scheduling, and customizable outputs. Reduces manual ops effort and increases audit confidence.
Read moreAlternate Payment Methods
Drop-in widgets for PayPal, Apple Pay, Google Pay, Samsung Pay, Pay by Bank, and BNPL providers like Klarna. Maximizes conversions with seamless one-click checkout.
Read more
Quickstart
Local Setup via Docker
# One-click local setup
git clone --depth 1 --branch latest https://github.com/juspay/hyperswitch
cd hyperswitch
scripts/setup.sh**This script: **
- Detects Docker/Podman
- Offers multiple deployment profiles:
- Standard: App server + Control Center
- Full: Includes monitoring + schedulers
- Minimal: Standalone App server
- Provides access links when done
If you need further help, check out our video tutorial.
π After setup, configure a connector and test a payment.
Hosted Sandbox (No Setup Required)
Hyperswitch offers a fully hosted sandbox environment that requires no setup. You can explore the Control Center, configure payment connectors, and test payments directly from the UI.
** What you can do in the Hosted Sandbox**
- Access the full Control Center
- Configure payment connectors
- View logs, routing rules, and retry strategies
- Try payments directly from the UI
**Cloud Deployment**
You can deploy to AWS, GCP, or Azure using Helm Charts.
Cloud Deployment Instructions.
Architectural Overview
Why Hyperswitch?
Hyperswitch is a commercial open-source payments stack purpose-built for scale, flexibility, and developer experience. Designed with a modular architecture, Hyperswitch lets you pick only the components you needβwhether itβs routing, retries, vaulting, or observabilityβwithout vendor lock-in or bloated integrations.
Built in Rust for performance and reliability, Hyperswitch connects to Stripe, Adyen, Braintree, Worldpay, Checkout.com, Cybersource, and 120+ processors β exposing smart routing and retry logic, and provides a visual workflow builder in the Control Center. Whether you're integrating a full payment suite or augmenting an existing stack with a single module, Hyperswitch meets you where you are.
Common starting points: teams moving from a single Stripe/ Stripe connect or Braintree integration to multi-PSP routing, merchants replacing a payment gateway with direct acquirer connections to TSYS, JP Morgan Payments, or other acquirers, and merchants rearchitecting their payments platform through Hyperswitch while keeping their existing VGS, TokenEx or other existing vault intact.
βLinux for Paymentsβ β Hyperswitch is a well-architected reference for teams who want to own their payments stack.
We believe in:
** Embracing Payment Diversity:** Innovation comes from enabling choiceβacross payment methods, processors, and flows.
** Open Source by Default:** Transparency drives trust and builds better, reusable software.
** Community-Driven Development:** Our roadmap is shaped by real-world use cases and contributors.
** Systems-Level Engineering:** We hold ourselves to a high bar for reliability, security, and performance.
** Maximizing Value Creation:** For developers, customers, and partners alike.
** Community-Driven, Enterprise-Tested:** Hyperswitch is built in the open with real-world feedback from developers and contributors, and maintained by Juspay, the team powering payment infrastructure for 400+ leading enterprises worldwide.
Supported Connectors
Hyperswitch integrates with 100+ payment processors out of the box. Each connector has a dedicated guide covering credentials setup, webhook configuration, supported payment methods, and common failure modes.
| Processor | Type | Guide |
|---|---|---|
| Global Payments | Payment Gateway | View β |
| Stripe | Payment Gateway | View β |
| Paypal | Payment Gateway | View β |
| Adyen | Payment Gateway | View β |
| Bank of America | Payment Gateway | View β |
π Browse all available connectors β
Hyperswitch Ecosystem Mapping
Hyperswitch is built as a set of modular services and SDKs that work together. The Rust app server in this repo is the core, and the repositories below extend it with dashboards, client SDKs, and deployment tooling.
1. Core backend services
The Rust services that process payments. The app server is the center of gravity; the vault and encryption service handle sensitive-data operations alongside it. hyperswitch-prism is a separate, lighter entry point: a unified connector library that can be used directly against payment processors without running the full switch. decision-engine is another standalone service: a routing control plane that selects the best gateway per transaction and can run independently of any orchestrator.
| hyperswitch | card-vault | encryption-service | prism | decision-engine | |
|---|---|---|---|---|---|
| Language | Rust | Rust | Rust | Rust | Rust |
| Role | App server. Routing, retries, vaulting, observability. | PCI-compliant card storage. | Encryption, decryption, KMS. | Unified connector library, 100+ processors. | Routing control plane. Rule-based and success-rate gateway selection. Standalone, works with any orchestrator. |
| Depends on | card-vault, encryption-service | encryption-service | None | None | None |
2. Dashboard
Merchant-facing UIs for configuring connectors, routing, and viewing transactions. Both require the hyperswitch backend to be running.
| control-center | control-center-embedded | |
|---|---|---|
| Language | ReScript | TypeScript |
| Role | Full merchant dashboard. Connectors, routing rules, analytics, API keys. | Embeddable Hyperswitch components for partners and merchants surfacing Hyperswitch UI inside their own apps. |
| Depends on | hyperswitch backend | hyperswitch backend |
3. Web checkout SDKs
How a browser talks to Hyperswitch. hyperswitch-client-core is the shared core, pulled in as a git submodule by every client SDK (web and mobile). hyperswitch-sdk-utils holds shared assets that merchants doing Headless Implementations consume directly.
| hyperswitch-web | client-core | react-hyper-js | sdk-utils | |
|---|---|---|---|---|
| Language | ReScript | ReScript | ReScript | ReScript |
| Distribution | npm | git submodule | npm | git submodule |
| Role | Primary web SDK. ReScript-built React library for unified checkout. | Shared SDK core consumed transitively by every client SDK. | Idiomatic React wrapper around the Hyper JS loader. | Shared utilities and assets used across client-core and hyperswitch-web. |
| Depends on | hyperswitch backend | None | hyperswitch-web | None |
4. Mobile SDKs
Native SDKs for embedding Hyperswitch checkout into mobile apps. All are built on top of hyperswitch-client-core, pulled in as a git submodule.
| Android | iOS | React Native | Flutter | |
|---|---|---|---|---|
| Repository | hyperswitch-sdk-android | hyperswitch-sdk-ios | react-native-hyperswitch | flutter_hyperswitch |
| Language | Kotlin | Swift | TypeScript | Dart |
| Distribution | Maven | CocoaPods (SPM in progress) | npm | pub.dev |
| Status | Officially supported | Officially supported | Officially supported | Officially supported |
[!IMPORTANT]
An older repo,hyperswitch-sdk-react-native, is being deprecated and has already been removed from npm. Usereact-native-hyperswitchinstead.
5. Deployment & infrastructure
Tooling for running Hyperswitch, from local development through production.
| hyperswitch-suite | hyperswitch-helm | |
|---|---|---|
| Tooling | Terraform (HCL) | Helm charts |
| Role | Umbrella full-suite deployment that wires the core, vault, control-center, and web together. Recommended starting point for the full stack. | Kubernetes deployments for GCP, Azure, or any K8s-compatible platform. |
Contributing
We welcome contributors from around the world to help build Hyperswitch. Whether you're fixing bugs, improving documentation, or adding new features, your help is appreciated.
Please read our contributing guidelines to get started.
Join the conversation on Slack or explore open issues on GitHub.
Feature requests & Bugs
For new product features, enhancements, roadmap discussions, or to share queries and ideas, visit our GitHub Discussions
For reporting a bug, please read the issue guidelines and search for existing and closed issues. If your problem or idea is not addressed yet, please open a new issue.
Versioning
Check the CHANGELOG.md file for details.
Copyright and License
This product is licensed under the Apache 2.0 License.
2. Official Technical Reference & Guides (juspay/hyperswitch-docs)
Try Hyperswitch and explore its modular architecture for a secure, streamlined
payments
icon: compass
cover: .gitbook/assets/Hero visual V6 (2).png
coverY: 0
metaLinks:
alternates:
- ./
Exploration Guide
Hyperswitch gives you full control over your payments infrastructure without the complexity of building from scratch. Whether you're validating a prototype or scaling globally, you can get started in minutes.
Try Hyperswitch Product Quickly
Use our hosted sandbox or Playground to explore the product quickly :
Cloud Sandbox (Hyperswitch Hosted Test Environment)
Try Hyperswitch β
Launch a ready-to-use Control Center test environment. No setup required, just log in and run your first transaction.
Hosted playground environment (pre-configured)
Try all our product features in a pre-configured playground environment
Try Hyperswitch Deployment Quickly
Deploy using Docker or Helm charts in local or a cloud environment:
Local Deployment (Docker)
Set up Docker Locally β
Perfect for developers who want local control and flexibility.
Local Deployment (Helm charts)
Set up Docker Locally β
Perfect for architects and infrastructure teams who want view all available components.
Scalable, Self-Hosted Deployment | Helm Charts for AWS, GCP & Azure
Install Hyperswitch on your cloud infrastructure using Helm charts for Kubernetes. This method gives you full control over your environment and is ideal for teams deploying on GCP, Azure, or any Kubernetes-compatible platform.
Hyperswitch Capabilities Overview
Power only what you need with Hyperswitchβs modular architecture. You can pick and integrate the components that solve your specific payment challenges without unnecessary overhead.
Power Only What You Need with Hyperswitchβs Modular Architecture
Dynamically route transactions based on geography, cost, or success rate to reduce failures and fees.
Recover failed payments using machine learningβbased retry logic that adapts to card network behavior.
Securely store and reuse payment credentials across providers β ideal for subscriptions and saved cards.
Gain real-time visibility into your processing costs and optimize spend across processors.
Automatically match transaction data across banks, PSPs, and internal systems to reduce manual effort.
Apply 3DS only when necessary, minimizing friction while keeping fraud under control.
Automate disbursements to vendors or sellers with rule-based routing logic.
Explore Core Payment Flows and Capabilities
Power only what you need with Hyperswitchβs modular architecture. Integrate just the components that solve your payment challenges, without the extra overhead.
Build Smarter Payment Flows
Automate and optimize how payments are routed, authorized, and split across providers with Hyperswitchβs flexible payment orchestration engine.
Tokenization and Card Vault β
Securely store and reuse customer payment credentials across processors to reduce friction and improve retention.
Get Started with Hyperswitch's Vault.
Control how transactions flow across payment providers with configurable routing logic and fallback options
Automatically route transactions based on geography, success rate, or cost to maximize authorization rates.
Recover failed payments using ML-driven retry strategies optimized for timing, issuer behavior, and card type.
Easily manage and automate disbursements to sellers, vendors, or partners with flexible payout logic.
Handle recurring payments seamlessly with built-in support for subscription billing and invoicing.
Divide transactions between multiple parties or accounts with precision and control.
Improve Your Checkout and Payment Experience
Deliver seamless, flexible, and localized payment flows that drive higher conversion and customer trust.
Create Seamless Checkout Experiences That Convert
Customizable Checkout SDK (Web) β
Embed a native, responsive checkout experience into your website with full control over styling and flow.
Click to Pay β
Enable frictionless, one-click payments for returning users using wallets and saved cards.
Payment Methods Management β
Dynamically configure and prioritize payment methods based on geography, currency, and user preference.
Alternate Payment Methods (APMs) β
Offer support for UPI, wallets, and local payment options to meet your customers where they are.
Integration Guide Overview β
Explore the full set of tools and options to deliver a branded and consistent payment experience across platforms.
Manage and Monitor Your Payment Operations
Operate at scale with tools to manage accounts, monitor transactions, handle disputes, and apply business rules.
Operate and Monitor Your Payment Stack
Manage Accounts and Profiles β
Create, manage, and operate across multiple merchant accounts and profiles with full multi-tenancy support.
Analytics and Operations β
Gain real-time visibility into transaction performance, routing behavior, and operational metrics.
Disputes and Chargebacks β
Monitor, respond to, and manage disputes or chargebacks from a centralized operations interface.
Surcharge Management β
Apply dynamic surcharges or convenience fees based on card type, geography, or business logic.
Full Operations Overview β
Explore the complete set of tools available for scaling your payment operations with confidence.
Scalability, Relability, and Security
Take your Hyperswitch integration to production with confidence. Set up environments, secure credentials, monitor performance, and scale seamlessly as your business grows.
Explore Security, Reliability, and Scalability
Build with confidence on an architecture designed for compliance, low-latency scaling, and enterprise-grade uptime.
Security and Compliance β
Protect sensitive data and meet global compliance standards like PCI DSS with secure-by-default components.
Latency β
Scale effortlessly with a stateless architecture designed to handle high-throughput payment workloads with near-zero overhead.
Here's how Hyperswitch handles horizontal scaling under high throughput
Reliability β
Achieve consistent uptime and resiliency through modular design and built-in fault tolerance.
Here's how Hyperswitch handles idempotency and message ordering.
Go Live with Hyperswitch
Take Hyperswitch into production
How to Go Live with Hyperswitch β
Follow our go-live checklist to launch with confidence β covering setup, credentials, security, and monitoring.
Need Help?
- Join our Slack Community β
Ask questions, share ideas, and connect with other developers building on Hyperswitch. - Contact Us β
Prefer direct support? Weβre happy to help.