Hyperswitch - Open Source Payments Orchestration

Payments get messy as soon as one processor is no longer enough.

A simple checkout flow can start with Stripe or PayPal.

Then the business adds a second processor for a new region, a fallback provider for downtime, a cheaper acquirer for specific cards, a wallet method, 3DS rules, retries, disputes, refunds, payout flows, and reporting.

That is the point where payment logic becomes infrastructure.

Hyperswitch is an open-source payments orchestration stack for routing payments across processors, managing payment methods, configuring retries, handling refunds, and operating a multi-provider payments layer.

What is Hyperswitch?

Hyperswitch is a payment switch.

Your application sends payment requests to Hyperswitch; Hyperswitch coordinates the actual processor call.

That means the app can talk to one API while Hyperswitch handles connector-specific details for Stripe, Adyen, Braintree, PayPal, Worldpay, Checkout.com, Cybersource, Klarna, GoCardless, JPMorgan, and many more providers.

The project is not a billing system in the Lago sense.

It does not primarily decide what the customer owes from product usage.

It sits closer to the transaction layer: authorization, capture, routing, retries, payment method handling, refunds, payouts, webhooks, and payment operations.

The useful mental model is:

Checkout or app request -> Hyperswitch -> Selected processor -> Payment result

Where Hyperswitch Fits with Lago and Zoneless

The earlier Lago post covered billing infrastructure: usage events, pricing, subscriptions, credits, invoices, and revenue workflows.

The Zoneless post is a different part of the map again: a lighter payment-system angle around stablecoin payments and checkout-style flows.

Hyperswitch sits between those worlds. Lago answers “what should be charged and why?” Hyperswitch answers “which payment rail or processor should handle this transaction, and how do we operate that flow?” Zoneless is smaller and more focused; Hyperswitch is a broad payment orchestration control plane.

One-line license comparison: Hyperswitch is Apache-2.0 and permissive, Lago is AGPL-licensed open-core, and Zoneless looks closer to the completely-open lightweight end of the payment tooling map.

Tech Overview of Hyperswitch

The checked-out repository is a large Rust workspace. The root Cargo.toml uses Rust 2021 edition, declares Apache-2.0 as the workspace license, and sets Rust 1.85.0 as the minimum supported Rust version.

The most important services are:

Router: the main Rust API server that receives payment, refund, customer, payment-method, connector, routing, webhook, and admin requests.
Scheduler: background producer/consumer services for delayed jobs and operational work.
PostgreSQL: durable storage for merchants, customers, payments, connector accounts, routing, keys, refunds, disputes, and other payment records.
Redis: caching, queueing, locks, and scheduler handoff.
Control Center: the browser dashboard for configuring and operating the stack.
Web SDK/demo service: browser-facing payment components and local testing support.
Optional observability stack: Grafana, Prometheus, Loki, Tempo, OpenTelemetry Collector, Kafka, ClickHouse, OpenSearch, and Vector through Compose profiles.

The source tree shows the scale of the integration work. In this checkout, the connector crate contained 154 connector files under crates/hyperswitch_connectors/src/connectors.

The API surface is broad. The OpenAPI specs include payments, refunds, customers, saved payment methods, payment method sessions, merchant accounts, organizations, connector accounts, routing algorithms, API keys, mandates, disputes, payouts, subscriptions, tokenization, proxy/relay endpoints, webhooks, and 3DS/authentication flows.

Self-Hosting Hyperswitch with Docker

Hyperswitch has an official Docker path, but it is not a tiny one-file compose like some homelab apps.

The upstream quickstart is:

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

The setup script checks for Docker or Podman, checks common ports, writes one-click setup state, and asks which profile to run.

The standard profile is the best first trial because it starts the app server, Control Center, web SDK, PostgreSQL, and Redis. The full profile adds monitoring and scheduler services. The standalone profile is useful when you only want the API server path.

Home-Lab Wrapper Compose

For the Foss Engineer Home-Lab repo, I kept the Docker file honest: it wraps the official compose instead of copying a huge bundle of upstream config, scripts, migrations, and seed files.

Home-Lab Hyperswitch Docker Compose

name: hyperswitch

# This Home-Lab helper intentionally wraps the official Hyperswitch compose file.
# The upstream compose mounts repo-local config, scripts, and migrations, so clone
# Hyperswitch first and point HYPERSWITCH_REPO at that checkout.
include:
  - path: ${HYPERSWITCH_REPO:?Clone https://github.com/juspay/hyperswitch and set HYPERSWITCH_REPO}/docker-compose.yml

Use it like this:

mkdir -p ~/Docker
git clone --depth 1 --branch latest https://github.com/juspay/hyperswitch ~/Docker/hyperswitch-src

mkdir -p ~/Docker/hyperswitch
cd ~/Docker/hyperswitch

cp /path/to/Home-Lab/hyperswitch/.env.sample .env
sed -i "s#^HYPERSWITCH_REPO=.*#HYPERSWITCH_REPO=$HOME/Docker/hyperswitch-src#" .env

docker compose --env-file .env config
docker compose --env-file .env up -d

The official compose defaults to these ports:

Port	Service
`8080`	Hyperswitch API server
`8081`	Superposition demo/config service
`9000`	Hyperswitch Control Center
`9050`	Hyperswitch web SDK/demo service
`5432`	PostgreSQL
`6379`	Redis

Those last two are common conflict points on a developer workstation.

If you already have Postgres, Redis, Lago, Supabase, or another stack running, check ports before starting Hyperswitch.

ss -ltnp | grep -E ':8080|:8081|:9000|:9050|:5432|:6379'

alt text

Field Note: Compose Validation

I cloned the repo shallowly into /tmp/hyperswitch; the checkout was about 344 MB.

These validation commands succeeded:

docker compose -f /tmp/hyperswitch/docker-compose.yml config
docker compose -f /tmp/hyperswitch/docker-compose-development.yml config
HYPERSWITCH_REPO=/tmp/hyperswitch docker compose config

I did not boot the full stack in this pass. The compose uses repo-local config, scripts, migrations, and several payment/dashboard/support containers. It also exposes ports that are commonly already occupied on a homelab machine, especially 5432 and 6379.

Safe Exposure Notes

Treat Hyperswitch as payment infrastructure, not as a casual dashboard.

Do not expose a local test instance directly to the public internet. For a private lab, bind behind a VPN or a carefully configured reverse proxy. For production, you need HTTPS, secret rotation, locked-down admin access, connector webhook hardening, backups, monitoring, incident logs, and a clear PCI/compliance model.

The default local config includes development-friendly values such as broad CORS and local test secrets. Those are convenient for first launch, but they are not production controls.

Hyperswitch vs Lago vs Stripe Billing

Pick Hyperswitch if you want to operate a multi-processor payments layer.

Pick Lago if you need usage metering, pricing models, subscriptions, wallets, credits, and invoices before payment collection.

Pick Stripe Billing directly if your payment and billing model fits Stripe cleanly and you do not need a separate open-source control plane.

Pick Zoneless if you are specifically exploring a smaller, stablecoin-oriented payment flow rather than a broad PSP orchestration stack.

These projects can also be complementary. A SaaS could use Lago to determine what should be billed, Hyperswitch to orchestrate how a payment is attempted, and processor-specific dashboards only as downstream rails.

Conclusion

Hyperswitch is a serious project for a serious part of the stack.

It makes most sense when payments are already complicated: multiple processors, regional routing, authorization-rate optimization, retries, refunds, alternative payment methods, dashboards, payment method storage, and operational auditing.

For a self-hoster, the right first step is local only: run the standard Docker setup, configure a sandbox connector, create a test payment, inspect the dashboard, and only then think about whether it belongs near real payment traffic.

FAQ

Yes. The upstream quickstart uses:

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

For a non-interactive Home-Lab-style wrapper, set HYPERSWITCH_REPO to the local clone and run docker compose --env-file .env up -d from the wrapper folder.

After the Standard Docker setup finished, the Control Center was available at:

http://localhost:9000

The default local demo credentials were:

Email: [email protected]
Password: Hyperswitch@123

Use these only for local testing. Do not carry demo credentials into a real deployment.

Two things blocked the local UI here.

First, Lago was already using Hyperswitch’s default PostgreSQL and Redis ports, so I stopped Lago without deleting volumes:

cd ~/Docker/lago
docker compose down

Second, the upstream superposition-init container tried to run a Bash script with sh, which failed with:

/seed_superposition.sh: line 53: syntax error: bad for loop variable

For this local checkout, I patched /tmp/hyperswitch/docker-compose.yml to install Bash and run the seed script with Bash:

- command: sh -c "apk add --no-cache curl jq yq && sh /seed_superposition.sh"
+ command: sh -c "apk add --no-cache bash curl jq yq && bash /seed_superposition.sh"

Third, the migration runner applied the database migrations but exited nonzero while regenerating Diesel schema output:

Failed to apply patch: error applying hunk #5

For this local UI trial, I let that schema-generation error stop blocking startup:

- just migrate"
+ just migrate || true"

Then I recreated the blocked services:

cd /tmp/hyperswitch
docker compose -f docker-compose.yml up -d --force-recreate \
  migration_runner superposition-init hyperswitch-server hyperswitch-web \
  hyperswitch-control-center create-default-user poststart-hook

After that, http://localhost:9000 returned 200 OK, the API returned health is good, and the default-user job exited successfully.

These are local trial notes, not a production recommendation. For production, fix the compose and migration behavior cleanly against a known Hyperswitch release instead of ignoring migration-runner exit codes.

Check at least:

ss -ltnp | grep -E ':8080|:8081|:9000|:9050|:5432|:6379'

The official local compose exposes the API on 8080, Control Center on 9000, web SDK/demo service on 9050, Superposition on 8081, PostgreSQL on 5432, and Redis on 6379.