# Hyperswitch: a modular open source payments stack you can run yourself

> Juspay's Hyperswitch is a Rust payments platform that sits between your application and 120+ processors, letting you adopt routing, retries, vaulting or reconciliation one module at a time. The local Docker setup is one script; the hard part is the connector configuration that follows.

**juspay/hyperswitch** — Hyperswitch is a composable open-source payments platform in Rust, linking multiple payment providers with intelligent routing, cost observability, and reconciliation.

- Repository: https://github.com/juspay/hyperswitch
- Website: https://hyperswitch.io/
- Stars: 45,251 · Forks: 6,415
- Language: Rust
- License: Apache-2.0
- Published: 2026-08-08 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/juspay-hyperswitch

## The problem Hyperswitch targets: one integration, many processors

Most teams start with a single processor because it is the shortest path to accepting money. That choice becomes expensive later. Adding a second acquirer usually means a second integration, a second set of webhooks, a second reconciliation file format, and a second place where card data might land. Hyperswitch exists to put a layer between your application and that set of processors. The README describes connectivity to Stripe, Adyen, Braintree, Worldpay, Checkout.com, Cybersource and "120+ others", with routing, retries and vaulting as separate concerns rather than one bundle.

The audience is narrower than the description suggests. This is for teams that already process payments and now want to route between providers, recover failed recurring charges, or audit what they pay in fees. A pre-revenue product does not need intelligent routing because it has nothing to route between. The README is explicit that the modules are independent and can be layered on an existing stack, which is the more realistic entry point: keep your current gateway, add reconciliation or cost observability beside it.

## How the Rust service and its modules fit together

The repository is a Cargo workspace. Cargo.toml declares members = ["crates/*"] and pins package.rust-version = "1.85.0", so the business logic lives in crates rather than a single binary crate. The top level also carries migrations/ and v2_migrations/ directories alongside diesel.toml and diesel_v2.toml, which tells you the schema is versioned in the repository and applied by a migration step rather than created at runtime.

That migration step is visible in docker-compose.yml. A service named migration_runner uses docker.io/debian:trixie-slim, installs the Diesel CLI at v2.3.5, installs just, and then runs just migrate with working_dir set to /app. The application does not start against an empty database; the compose file sequences a prestart-hook and a migration runner ahead of it. Postgres runs as docker.io/postgres:latest with POSTGRES_USER=db_user, POSTGRES_PASSWORD=db_pass and POSTGRES_DB=hyperswitch_db, and Redis runs as docker.io/redis:7 on port 6379. Both have healthchecks, which is how the dependent services know when to proceed.

The build is a two-stage Dockerfile. The builder stage is public.ecr.aws/docker/library/rust:trixie, installs libpq-dev, libssl-dev, pkg-config and protobuf-compiler, then builds with --no-default-features --features release --features ${VERSION_FEATURE_SET}. Two build arguments matter for anyone compiling this themselves: CARGO_BUILD_PROFILE defaults to release, and the Cargo.toml defines a release-fast profile that inherits release but sets lto = false, codegen-units = 16 and strip = "none". The comment in Cargo.toml says release-fast is for development cycles and is "never the default". The default release profile is the opposite: strip = true, lto = true, codegen-units = 1. That is a slow build by design, and it is the single most predictable cost of working on this codebase.

## Local setup with scripts/setup.sh

The README's quickstart is three commands. It clones the latest branch shallowly, changes directory, and runs a shell script. The script detects Docker or Podman and then asks which deployment profile you want: Standard (application server plus Control Center), Full (adds monitoring and schedulers), or Minimal (standalone application server). It prints access links when it finishes.

```bash
git clone --depth 1 --branch latest https://github.com/juspay/hyperswitch

cd hyperswitch

scripts/setup.sh
```

What you should see is the compose stack come up with Postgres on 5432 and Redis on 6379, the migration runner completing, and a set of URLs for the application and the Control Center. If the migration runner is the last thing running, the schema has not been applied yet and the application will not be usable.

The README does not stop at "it started". It points to two follow-on steps: configure a connector, then test a payment. That ordering is the honest description of the work. Starting the stack proves nothing about whether you can process a transaction.

If you would rather not run anything, the project offers a hosted sandbox at app.hyperswitch.io. The README lists what it covers: the full Control Center, connector configuration, logs, routing rules and retry strategies, and the ability to try payments from the UI. For evaluating whether the routing model matches how you think about your own traffic, that is faster than a local build. It is not a substitute for the local stack if you need to inspect the database or the configuration files.

For production, the README points to Helm charts for AWS, GCP and Azure rather than describing a topology. That is a real gap in the README itself: the deployment shape lives in the docs site, not in the repository's front page.

## What the module list does not tell you

The README's module descriptions are specific about intent and quiet about mechanics. Intelligent Routing is described as routing each transaction to the processor with the highest predicted auth rate. Predicted by what model, trained on whose data, and updated how often is not stated in the README. Revenue Recovery is described as retry strategies tuned by card bin, region and method, with control over retry algorithms and penalty budgets. The existence of a penalty budget implies retries have a cost you are budgeting against, which is a more honest framing than most retry features get, but the README does not say how the budget is enforced.

The Vault module is the one with the clearest operational consequence. It stores cards, tokens, wallets and bank credentials, and the README says it supports bring-your-own-vault by connecting existing providers including VGS and TokenEx "without re-tokenizing or migrating stored cards". That sentence is doing a lot of work. It is the difference between adopting Hyperswitch as a routing layer and adopting it as the place your card data lives. The first is a configuration change; the second touches your PCI scope. The README asserts PCI compliance as a property of the project, but compliance is a property of a deployment, not of a codebase, and the README does not walk through the shared responsibility boundary.

Cost Observability promises to detect hidden fees, downgrades and penalties through self-serve dashboards. Reconciliation promises 2-way and 3-way matching with backdated support and staggered scheduling. Both depend on ingesting processor statements, and the README does not describe the statement formats or the failure mode when a processor changes one.

## Where Hyperswitch is the wrong tool

If you sell in one country through one processor and your volume is modest, Hyperswitch adds a Rust service, a Postgres instance, a Redis instance and a migration pipeline to a problem you do not have. The README's own framing supports this: it lists common starting points as teams moving from a single Stripe or Braintree integration to multi-PSP routing, merchants replacing a gateway with direct acquirer connections, and merchants rearchitecting while keeping an existing vault. Every one of those describes a team that has already outgrown a single integration.

The second case is narrower and worth stating plainly. If your requirement is a checkout page, Hyperswitch is not a checkout page. It is infrastructure that sits behind one. The alternate payment method widgets for PayPal, Apple Pay, Google Pay, Samsung Pay, Pay by Bank and BNPL providers are described as drop-in, but they are drop-in onto an application that already has Hyperswitch running.

The third case is operational. A payments service that cannot be upgraded without a migration is a service you have to staff. The repository carries both migrations/ and v2_migrations/ directories with separate Diesel configuration files, and the compose file runs migrations as a distinct step before the application starts. That is the correct design, and it also means every version bump is a deployment you have to plan. Teams without anyone who owns that will find it heavier than a hosted gateway.

## Hyperswitch compared with staying on Stripe

The comparison people search for is Hyperswitch versus Stripe, and the difference is structural rather than feature-by-feature. Stripe is a processor and a platform in one: you integrate once, and the routing, retries and vaulting are decisions Stripe makes on your behalf. Hyperswitch is the layer above that. The README lists Stripe among the processors it connects to, which means the two are not mutually exclusive. You can run Hyperswitch with Stripe as one of several connectors.

What you gain is control over the routing decision and visibility into cost and settlement. What you take on is the operation of the layer itself, plus the work of maintaining credentials and configuration for every processor you add. A single-processor team using Hyperswitch has rebuilt Stripe's job without Stripe's scale. A multi-processor team using Stripe alone has given up the routing decision entirely.

The honest middle ground is the one the README describes as augmenting an existing stack with a single module. Reconciliation and cost observability are the easiest to justify that way, because they read data rather than sit in the authorization path. Intelligent routing is the hardest, because it sits in the path of every transaction and its failure mode is a declined payment.

## Licence, maintenance and upgrade cost

Hyperswitch is Apache-2.0, and Cargo.toml sets package.license = "Apache-2.0" at the workspace level. Apache-2.0 permits commercial use and modification and includes a patent grant. It does not obligate you to publish changes. The README's own licence section is titled "Copyright and License" and links to the LICENSE file at the repository root. Nothing here is legal advice; if you are embedding this in a product, read the LICENSE and NOTICE files yourself, since the repository ships a NOTICE file and that file carries its own implications for redistribution.

The project is not archived. The most recent release in the repository is v1.126.0, dated 2026-08-24, with v1.125.0 on 2026-07-10 and v1.124.0 on 2026-06-30. That is a release cadence measured in weeks, and the version numbering has moved past 1.120, which means the surface you integrate against is still changing. The README has a Versioning section, so version policy is documented, but the practical consequence is that a pinned version is the only sane way to run this in production.

Upgrade cost is dominated by two things. First, the database: migrations are applied by a separate runner and the repository maintains two migration trees, so a version jump may include schema work you have to schedule. Second, the build: the default release profile uses LTO with codegen-units = 1, which is the slowest configuration Cargo offers. The release-fast profile exists precisely because of that, and the comment says it is for development cycles, not production.

## Conclusion

Adopt Hyperswitch if you already run payments at a volume where a second acquiring route or a retry policy is worth engineering time, and you are comfortable operating Postgres, Redis and a Rust service yourself or paying for the hosted version. Do not adopt it as a first payments integration for a small product: the module list is wide, but each module still needs a processor account and configuration behind it. Before committing, verify the connector you actually need is supported, confirm how the vault decision interacts with your existing tokenization, and read the deployment docs for the profile you intend to run, since the README points at Helm charts rather than describing the topology.

## FAQ

### What is Hyperswitch?

It is an open source payments platform from Juspay, written in Rust and licensed under Apache-2.0. It connects an application to payment, payout, fraud, vault and tokenization providers, and exposes routing, retries, vaulting, reconciliation and cost observability as separate modules you can adopt individually.

### What is Juspay HyperSwitch?

The same project: Hyperswitch is maintained by Juspay, and the README describes it as a commercial open source payments stack. The repository is juspay/hyperswitch on GitHub, with the source under a Cargo workspace of crates.

### Is Hyperswitch safe?

The README states that the Vault module is a PCI-compliant service for storing cards, tokens, wallets and bank credentials, and the project is Apache-2.0 licensed. PCI compliance applies to a deployment rather than a codebase, so what that means for your scope depends on how you run it and whether you use the built-in vault or bring your own.

### How does Hyperswitch compare with Stripe?

They operate at different levels. Stripe is a processor; Hyperswitch is a layer that routes across processors and the README lists Stripe among the 120+ it connects to. Running Hyperswitch with Stripe as a connector is a supported configuration rather than an either-or choice.

### What are the alternatives to Hyperswitch?

The realistic alternative is staying on a single processor and accepting its routing and retry decisions, or using a hosted gateway that handles that layer for you. Hyperswitch's difference is that the routing decision, the retry policy and the vault all become configuration you own, at the cost of running the service yourself.

## Sources

- [Official documentation](https://hyperswitch.io/)
- [Official README](https://github.com/juspay/hyperswitch#readme)
- [Project repository](https://github.com/juspay/hyperswitch)
- [Release notes](https://github.com/juspay/hyperswitch/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/juspay-hyperswitch