HyperSwitch

Last reviewed Sep 13, 2026 · 831 words

Hyperswitch does not move money. It sits between your checkout and the processors that do, presenting one API over Stripe, Adyen, Checkout.com, PayPal, Braintree and dozens of others, and deciding per transaction which one to use. If you have one processor and a normal amount of volume, you do not need it, and installing it adds a Rust service, PostgreSQL, Redis and a control-plane UI between you and a payment that used to be one API call. If you have 2 or more processors, sell in several regions, or lose real revenue to a single provider's outages, it is the only open-source (Apache-2.0, 43,575 stars) tool doing this job, and the commercial alternatives are priced for enterprises.

Who runs this and why it is not you, probably

The people running Hyperswitch are engineering teams at merchants doing meaningful volume: marketplaces routing card payments through the cheapest processor per country, subscription businesses retrying failed charges through a second provider, companies that got fee-negotiated into a two-processor setup and needed one integration. Juspay, the maintainer, built it after running payment infrastructure at scale in India, and the design shows that. A self-hoster selling prints from a Medusa or WooCommerce store needs Stripe's own plugin and nothing else. The finance category is mostly personal budgeting and invoicing, and this project is the odd one out there for good reason.

The stack: router, control centre, SDK, and two data stores

The core is the router, a Rust service on port 8080 that exposes the payments API and talks to connectors. Around it: PostgreSQL for merchant, customer and payment records, Redis for state and rate limiting, a Control Center web app where you configure connectors and routing rules, and a browser checkout SDK that renders payment forms so card details flow to Hyperswitch rather than through your own frontend code. The repository ships a Compose file that brings up all of it plus a scheduler for retries, and for evaluation it is genuinely a 10-minute start. The Rust core is the reason the catalogue's 512 MB floor is honest; the router idles in tens of megabytes and Postgres and Redis are the ones that grow.

Configuration is a TOML file per environment with connector credentials, plus API keys created through the control centre. Every connector you add means a merchant account you already hold with that processor; Hyperswitch gives you no processing capability of its own.

Routing and retries are the features that justify the trouble

Rules-based routing lets you say "cards issued in the EU go to Adyen, everything else to Stripe, and if the first attempt fails with a network error try the other". Volume-split routing sends 20% of traffic to a new processor while you evaluate it. Automatic retries on soft declines, tokenised card vaulting so a customer's saved card works across processors, and unified webhooks that normalise 30 providers' event formats into one. This is a real reduction in complexity for the teams that have the problem. For everyone else it is complexity added.

The PCI question you must answer before the first transaction

If card numbers pass through a server you operate, that server is in PCI DSS scope, and that is what the checkout SDK does by design. Hyperswitch is built to be run in a compliant environment, with vaulting, key management and audit logging, but the compliance is yours to attest. Self-hosting on a homelab box or a shared VPS does not meet it. Teams running this do so in a locked-down cloud account with the router in a private network, secrets in a KMS, and a compliance process behind it; anything less and you have shifted risk from Stripe to yourself for no gain. Read the threat-modelling piece with card data specifically in mind.

Adjacent tools that solve the problem most people actually have

Wanting a self-hosted piece of the payments stack usually means one of two things. Subscription billing and metering: Lago does that and hands the actual charge to Stripe. Invoicing and payment links for a small business: Invoice Ninja with a Stripe gateway. Neither puts you in PCI scope, both run on a 1 GB VM, and both are where I would send the 95% of readers who arrived here searching for "self-hosted payments".

What I'd do

Single processor, under a few thousand transactions a month: integrate Stripe or your processor directly, keep card entry on their hosted elements, and do not run Hyperswitch. Multiple processors, multi-region, or a real outage cost: run it, but in a proper cloud account with a compliance owner, start with the Compose file to learn the routing model, then move to the documented production deployment before real traffic. It is excellent software for a problem most self-hosters should be glad they do not have.