Hyperswitch

What it is

Hyperswitch is an open source payments stack from Juspay, written in Rust. Your checkout calls one Hyperswitch API, and Hyperswitch sends each payment on to a processor such as Stripe, Adyen, Braintree, Worldpay or Checkout.com. The README says it connects to more than a hundred processors. Around that core sit separate modules for routing between processors, retrying failed payments, a card vault, a view of your payment costs, reconciliation and alternate payment methods. You take the modules you need and leave the rest. The README calls it a commercial open source stack, and the repository’s GitHub description offers SaaS and self-host options. This listing covers the repository and how to run it yourself.

1. Your checkout calls the Hyperswitch API with the payment
2. Routing rules choose a processor, such as Stripe or Adyen
3. The processor approves or declines the payment
4. Retry rules can try a failed payment again
5. The result comes back to your checkout

Who it suits

Teams that take card payments and want to own the layer between their checkout and their processors. The README names three starting points. Merchants on a single Stripe or Braintree integration move to several processors. Merchants replace a payment gateway with direct acquirer connections. Others rebuild their payments platform and keep the vault they already use, such as VGS or TokenEx. The docs page on self-hosting adds banks and payment institutions that want control on their own premises.

If you only need a handful of card payments through one processor, you may not need it. Self-hosting makes you the operator of a payments system, with its databases, keys and upgrades.

Where to use it

The README and Juspay’s docs document these routes.

• The one-click Docker script, with Docker or Podman on your own computer
• Plain Docker Compose, from the local setup page
• Helm charts on Kubernetes, which the README says can go to AWS, GCP or Azure
• The hosted sandbox at https://app.hyperswitch.io, which needs no install: the Helm chart page says to sign up there, and the Exploration Guide says to log in and run your first transaction
• Client SDKs for web, Android, iOS, React Native and Flutter, to put checkout into your own site or app

The README’s ecosystem section also lists a Terraform repository, hyperswitch-suite, as the recommended starting point for the full stack. The kit does not cover it.

How to set it up

Get it saves a zip of Mindket’s setup notes in your downloads folder, with the steps for the Docker, Helm, sandbox and web SDK routes. The main route is the one-click Docker script from the README.

1. Run the three lines below. They come from the README and go in a terminal.
2. Choose a profile by typing 1, 2 or 3. Option 1, Standard, is marked Recommended.
3. Wait while the services start. The script also checks their health.
4. Read the links it prints. With Standard or Full Stack, the Control Center is at http://localhost:9000. The App Server is at http://localhost:8080. The script prints these even when its health checks failed, so check them.
5. Sign in to the Control Center. With Standard or Full Stack, use the demo email and password the script prints.

git clone --depth 1 --branch latest https://github.com/juspay/hyperswitch
cd hyperswitch
scripts/setup.sh

Juspay’s local setup page gives a plainer route. It skips the script and the profiles.

git clone https://github.com/juspay/hyperswitch
cd hyperswitch
docker compose up -d

How to use it

The script ends by printing where each service listens. The README describes the Control Center as the merchant dashboard for connectors, routing rules, analytics and API keys. The App Server is the API your checkout calls. The README’s next steps are to add a payment connector in the Control Center and test a payment.

To check the server by hand, the local setup page gives this line. It says a 200 OK answer means the server and its database and Redis work.

curl --head --request GET 'http://localhost:8080/health'

The script prints the stop line for your profile. For Standard and Standalone it is the line below, with podman compose in place of docker compose when it found Podman.

docker compose down

For Full Stack it is this line.

docker compose --profile scheduler --profile monitoring --profile olap --profile full_setup down

Example

You run a shop that takes payments through one processor, and you want a second one ready. In the repository folder on your laptop, you run the script and type 1 for the Standard profile:

scripts/setup.sh

The script prints the Control Center at http://localhost:9000 and a demo email and password. You sign in, add a connector for each processor, set up routing between them and try a payment. The README says the hosted sandbox shows logs, routing rules and retry strategies, so you can try the same steps there first.

For newcomers and experts

If you are new. A payment processor is the company that moves the money for a card payment. Hyperswitch is not one. It sits between your checkout and the processors and decides which one gets each payment. A connector is the link between Hyperswitch and one processor. The simplest start is the hosted sandbox, with nothing to install. You sign up or log in there first. After that, run the Standard profile, add one connector and send one test payment. Leave the vault and the Helm route until that works.

For experts. The README splits the project into services. The Rust app server in this repository is the core, and it depends on a card vault and an encryption service. Two standalone projects sit beside it. hyperswitch-prism is a unified connector library for payment processors, and decision-engine is a routing control plane that works with any orchestrator.

On Kubernetes, the stack comes from the hyperswitch-stack chart. These are the chart page’s lines.

helm repo add hyperswitch https://juspay.github.io/hyperswitch-helm
helm repo update
kubectl create namespace hyperswitch
helm install hypers-v1 hyperswitch/hyperswitch-stack -n hyperswitch

The chart page says the card vault and its dependencies are installed by default. You still generate a master key and custodian keys, and open the locker with them, before it can save cards. The kit lists those steps.

The contributing guide says Hyperswitch makes heavy use of features, so common cargo commands need an extra argument. Formatting needs the nightly toolchain.

cargo check --all-features
cargo clippy --all-features
cargo test --all-features
cargo +nightly fmt

Good to know

This is payments software, and running it makes you responsible for what it holds.

• Not Juspay’s notes: Mindket wrote the kit. Juspay makes Hyperswitch, and the notes are not made or endorsed by Juspay
• Card data: the README calls the vault PCI-compliant. The docs page on self-hosting says that when you host it, you are fully responsible for your own PCI DSS certification and data handling
• What the script sends out: it calls a helper that sends the Hyperswitch version and the install status to hyperswitch.gateway.scarf.sh. On a failure it also sends the failed command and the last line of its error log. The script runs the helper first, before anything else, with set -Eeuo pipefail, so if the request cannot connect (offline or blocked), the script stops at its error handler. The script has no switch to turn this off, so read scripts/setup.sh and scripts/notify_scarf.sh first
• The demo login: the script prints a demo email and password for the Control Center. Read the password off its output
• Test data: the Exploration Guide calls the hosted sandbox a test environment
• Docs links: some documentation pages the README links answered with a server error or no answer on 3 November 2026, so the kit uses the pages that worked
• Updates: the README gives no update steps for the Docker route. It points to CHANGELOG.md for versioning details
• An older SDK: the README says hyperswitch-sdk-react-native is being deprecated and has been removed from npm. It names react-native-hyperswitch instead
• Not covered: the kit gives no install steps for the mobile SDKs, hyperswitch-suite, hyperswitch-prism or decision-engine, since their READMEs were not read
• License: Apache-2.0. The LICENSE file is the standard Apache License 2.0 text. The bracketed "Copyright [yyyy] [name of copyright owner]" at its end is the appendix’s boilerplate for applying the license, and the file names no copyright holder