Name: Hyperswitch Payments API
Availability: InStock
Author: onepush

Deploy and Host self hosted Hyperswitch Payments API (Open-Source Payments Orchestration) on Railway

This template runs hyperswitch-router, the Control Center, Postgres and Redis so your backend can create, confirm, capture and refund payments over one REST API. It is built for engineers testing the api-key flow.

About Hosting Hyperswitch Payments API open-source software on Railway (self hosted Hyperswitch Payments API template)

This template runs four services in your own Railway project: the hyperswitch-router API on port 8080, the Control Center dashboard on 9000, Postgres 18 and Redis 8.2. Your merchant records, API keys, connector credentials and the keys that encrypt stored payment data sit in your database, not a vendor's.

Railway wires Postgres and Redis for you, mounts the file volume and runs database migrations on router start.

Why Deploy Hyperswitch Payments API, the Stripe API alternative on Railway (Railway Free Trial)

Stripe takes a cut of every charge and owns the routing decisions. Self hosting flips that: you pay Railway about $15-30 a month plus acquirer fees, and routing, retries and the vault stay yours. The $5 trial is enough to finish a test-mode integration and watch the webhooks land.

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying Hyperswitch Payments API on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.

Railway vs Other Hosting Providers and VPS for Hyperswitch Payments API self hosting

Self hosting the router yourself means you also own the Postgres, Redis and migration plumbing, which is where most of the time goes.

Provider	What You Get with Railway	What You Get with the Other Provider
DigitalOcean	Four services wired, Postgres and Redis included	Droplets to patch plus a separate managed database
AWS	Images deployed with vars and a volume set	ECS plus RDS and ElastiCache, IAM and VPC to assemble
Hetzner	Router on 8080, dashboard on 9000, one click	Raw VMs, you install Docker, backups and TLS

Railway hands you all four on one bill.

Common Use Cases for hosted Hyperswitch Payments API

Server-created payment plus web SDK checkout: your backend calls POST /payments with amount 6540, gets client_secret back, and the frontend SDK finishes with the publishable key.
Authorize now, capture at shipping: send capture_method manual, park the payment in requires_capture, then POST /payments/PAYMENT_ID/capture with amount_to_capture.
Partial refunds: POST /refunds with payment_id and a smaller amount, then repeat later while funds remain.
Webhook-driven order updates: verify X-Webhook-Signature-512, dedupe on event_id, mark orders paid on payment_succeeded.
Second processor without code changes: add the connector in the Control Center and shift traffic with a volume split rule; the same API and statuses keep working.

Dependencies for Hyperswitch Payments API Docker hosted on Railway

The template ships four services: hyperswitch-router (ghcr.io/onepush-dev/hyperswitch-router:v1.128.0) on port 8080, control-center (juspaydotin/hyperswitch-control-center:v1.38.10) on port 9000, Postgres 18 and Redis 8.2. Everything your api-key calls need sits behind those.

Deployment Dependencies for Managed Hyperswitch Payments API Service (Payments Orchestration)

ROUTER__SECRETS__ADMIN_API_KEY is generated at 32 characters, JWT_SECRET at 48, and MASTER_ENC_KEY, HASH_KEY and ENCRYPTION_KEY are 64-character hex. Back up MASTER_ENC_KEY; lose it and stored rows stay unreadable.

Implementation Details for Hyperswitch Payments API (Using Hyperswitch official docker image)

The router image mounts /local/bin/files as a volume, exposes /health and /health/ready (database, redis, analytics), maps Railway's Postgres variables and runs migrations before start. No image build on your side. Keep the admin API key server side; it is for admin endpoints, not /payments.

How does Hyperswitch Payments API compare against other payments APIs

Hyperswitch vs Stripe API (Stripe Alternative)

Same call shape: Stripe keeps you on Stripe; Hyperswitch posts to whichever processor you connected.
Routing stays yours: volume split, priority and rule-based routing apply behind the same API.
Where Stripe wins: SDKs, docs and dispute tooling are more polished, and Stripe runs the servers.

Hyperswitch vs Adyen (Adyen Alternative)

No acquirer lock-in: Adyen is one acquirer; Hyperswitch fans out to 50+ processors in one API.
Cheap to try: connect a sandbox connector, create an API key, curl the router. No onboarding call.
Where Adyen wins: enterprise acquiring, local payment method depth and settlement.

Hyperswitch vs Spreedly (Spreedly Alternative)

Self hosted vault: tokens and MASTER_ENC_KEY stay in your own Railway project.
Apache-2.0: you can patch the Rust source; Spreedly is closed SaaS.
Where Spreedly wins: zero ops to run, and its gateway network is wider.

Hyperswitch vs Primer (Primer Alternative)

API first: routing rules exist, but the daily surface is REST calls with the api-key header.
Signed webhooks: X-Webhook-Signature-512 and event_id keep order state in sync.
Where Primer wins: its no-code workflow editor suits ops teams that never touch a backend.

How to use Hyperswitch Payments API (the OSS payment orchestrator)?

Sign up in the control center, create a merchant and profile, connect a test-mode processor.
Create an API key, then run:

R=https://router-domain
curl -X POST $R/payments -H "api-key: YOUR-SECRET-KEY" -H "Content-Type: application/json" -d '{"amount":6540,"currency":"USD","confirm":false,"capture_method":"manual"}'
curl -X POST $R/payments/PAYMENT_ID/confirm -H "api-key: YOUR-SECRET-KEY"
curl -X POST $R/payments/PAYMENT_ID/capture -H "api-key: YOUR-SECRET-KEY" -d '{"amount_to_capture":6540}'
curl -X POST $R/refunds -H "api-key: YOUR-SECRET-KEY" -d '{"payment_id":"PAYMENT_ID","amount":1000}'
curl $R/payments/PAYMENT_ID -H "api-key: YOUR-SECRET-KEY"

GET returns the live status; 6540 is 65.40 USD.

How to self host Hyperswitch Payments API on other VPS Services (Hyperswitch self hosting guide)

These steps assume Ubuntu 24.04, Docker Engine and the Compose plugin on a 4 GB box.

Clone the Repository

git clone https://github.com/juspay/hyperswitch
cd hyperswitch

Install Dependencies

Install Docker and the Compose plugin, then run the official setup helper from the repo:

sudo apt install -y docker.io docker-compose-v2
bash scripts/setup.sh

Configure Environment Variables

Replace the sample admin API key, JWT secret and the three 64-character hex keys in the repo's compose configuration with your own values. Point ROUTER__USER__BASE_URL at the control-center domain and its api_url at the router domain.

Start the Hyperswitch Payments API Application

docker compose up -d
curl http://your-domain:8080/health

Expect health is good; /health/ready reports database, Redis and analytics. Back up MASTER_ENC_KEY before your first payment.

Railway runs the same migrations, wires Postgres and Redis, and generates those keys for you.

Official Pricing of Hyperswitch Payments API (Hyperswitch pricing)

Hyperswitch is Apache-2.0 and free to self host, so there's no licence fee and no per-transaction cut from Juspay on this template. Juspay's hosted cloud is usage-based, and your processors still bill their own fees. Self hosting on a VPS of your own shifts that bill to your provider.

Hyperswitch Payments API cloud vs self hosted comparison (Pricing, features, costs, and more)

The API calls are the same either way: same /payments payloads, same statuses, same webhook envelope. Both give you the same routing rules and smart retries; self hosting just puts the uptime and key custody on you.

Monthly cost of self hosting Hyperswitch Payments API on Railway

Expect roughly $15-30/mo for the router, control center, Postgres and Redis at light test-mode use. Juspay's hosted cloud is usage-based and processors bill their own fees on top.

System Requirements for Hosting Hyperswitch Payments API on a VPS

You need Docker with compose, 4 GB RAM and up to 20 GB disk for the four services, plus a domain for the router and dashboard. Back up MASTER_ENC_KEY; lose it and stored data is unreadable.

Frequently Asked Questions (FAQs)

Which header carries the API key?

The api-key header, with the secret key you create in the Control Center. Keep it server side; the publishable key and client_secret are for the browser SDK.

Why is my payment stuck in requires_payment_method?

You posted with confirm false and no payment method attached yet, so nothing was authorized. Confirm it with the client SDK or POST /payments/PAYMENT_ID/confirm.

How do I capture later?

Send capture_method manual at creation, then POST /payments/PAYMENT_ID/capture with amount_to_capture up to the authorized amount. Omit the field for a full capture.

How do I verify webhooks?

Take the raw body bytes, HMAC-SHA512 them with the profile's payment_response_hash_key, and compare in constant time against X-Webhook-Signature-512. Dedupe on event_id.

Is the admin API key for payments?

No. ROUTER__SECRETS__ADMIN_API_KEY is for admin endpoints such as merchant accounts and connectors; payment calls use a Control Center API key.

Can I switch processors without code changes?

Yes. Routing rules, volume splits and smart retries live in the Control Center, so the same POST /payments hits a different connector.