Where Hyperswitch fits
Hyperswitch is an open-source payments orchestration platform from Juspay, licensed under Apache-2.0 and written in Rust. It puts one API in front of many payment processors and adds routing rules, retries, a vault for stored payment methods, reconciliation and a Control Center dashboard. The project lists connections to more than 100 processors, along with payout, fraud, vault and tokenization providers.
Juspay offers hosted and self-hosted options. Teams self-host for control over data residency, processor relationships and routing logic, or to place orchestration inside an existing PCI DSS environment. An implementation covers processor and method selection, connector setup, routing design, vault and key management, checkout integration, webhooks into order and ledger systems, reconciliation and operations.
Discovery: payment flows and processors
Write down flows, processors and data paths before configuring anything.
| Topic | What to map | Why it matters |
|---|---|---|
| Methods and markets | Cards, wallets, bank transfers and local methods per country and currency. | Decides which connectors and SDK components the build needs. |
| Processors and acquirers | Existing contracts, supported methods, settlement currencies and fees per processor. | Routing can only choose among processors you hold accounts with. |
| Flow types | One-time, saved card, recurring and merchant-initiated payments, refunds, disputes and payouts. | Each flow has its own vault, mandate and webhook needs. |
| Card data path | Whether raw card data reaches your servers, the Hyperswitch vault, a third-party vault or only processor-hosted fields. | Drives PCI DSS scope and the vault design. |
| Ledger and finance | How payment events reach your ledger, settlement report formats and who reconciles. | Shapes webhooks, reconciliation and reporting. |
Components to deploy
A self-hosted deployment runs several services. Give each one an owner, a scaling plan and a recovery path.
Router
The Rust core that receives API calls, applies routing and retry logic, calls connectors and records payments. The documentation describes it as stateless, so it scales horizontally.
PostgreSQL and Redis
PostgreSQL stores merchant, customer and payment data, with a primary and a read replica. Redis caches frequent lookups and queues work for the scheduler, which runs deferred tasks such as deleting saved card data.
Card vault
A separate Apache-2.0 Rust service for card and bank account data. Its master key is encrypted by custodian keys, each split between two custodians. A companion encryption service handles encryption and key management.
SDKs and Control Center
Web and mobile SDKs (Android, iOS, React Native, Flutter) render the checkout and collect payment details on the client side. The Control Center dashboard manages connectors, routing rules and API keys.
Connectors, routing and retries
Each connector needs production credentials, payment methods enabled to match the processor's dashboard, and a webhook secret so Hyperswitch can verify incoming webhooks. Some connectors require a PCI DSS Attestation of Compliance before raw card processing is enabled.
Rules pick a processor from attributes of the payment, such as method, region or amount, with a fallback order. Agree rules with the owner of each processor relationship, keep them under change control and test every branch in sandbox.
Hyperswitch can route by observed authorization rates and retry failed payments on another processor. Agree which decline codes are safe to retry, how retries respect card scheme rules on reattempts, and how retried payments appear in reporting so finance can follow them.
A missing processor or local method means writing a connector in Rust inside the connector framework. Decide whether to contribute it upstream or maintain it across releases, and test it against the processor's sandbox.
Vault design and PCI DSS scope
The card data path is the main architectural decision. Options include the self-hosted Hyperswitch card vault, a third-party vault such as VGS or TokenEx through Hyperswitch's modular vaulting, tokenization at the processor, and network tokens where they are enabled for the profile. Each option moves different systems into or out of the cardholder data environment.
The Hyperswitch documentation describes PCI scope as managed by Juspay for its hosted offering and shared when self-hosted. When you run the router and vault yourself, those components, the infrastructure under them and the people who operate them fall within your PCI DSS scope, and the project's own compliance statements do not cover your deployment. Confirm scope, segmentation and the assessment type with your QSA and acquirer before fixing the architecture.
For the vault, plan the custodian key ceremony, where key shares are held, rotation, and which KMS or HSM backs the encryption service in your version. Run it in its own network segment, reachable only from the router, and log every access.
Integration, reconciliation and testing
What connects to Hyperswitch?
The checkout through the web or mobile SDK, your backend calling the payments API with idempotent order references, webhooks into order management and the ledger, fraud providers, and finance systems that consume reconciliation output. Record which system holds the authoritative state for each payment.
How does reconciliation work?
Hyperswitch includes a reconciliation module for two-way and three-way matching across bank statements, processor settlement reports and internal records. Decide who works exceptions, how unmatched items age, and who signs off daily totals before they post to the general ledger.
What should testing cover?
The full lifecycle on processor sandboxes: authorization, capture, voids, refunds, disputes, 3DS challenges, saved cards and recurring charges, plus processor timeouts, failover and duplicate or out-of-order webhooks. On return URLs, verify the signed payload, amount and status before fulfilling an order.
Hosting, hardening and observability
Juspay publishes Helm charts for AWS, GCP and Azure and a Terraform-based deployment. Most production work happens around the cluster.
| Area | Plan | Check |
|---|---|---|
| Kubernetes | Deploy with the Helm charts or your own manifests, built from code. The vault ships with the deployment but is activated separately. | Each environment can be rebuilt from the repository. |
| Network edge | Put an incoming proxy with WAF, rate limiting and request validation in front of the cluster, and send processor traffic through an egress proxy outside it. | Only API and SDK endpoints face the internet, and egress is limited to processor endpoints. |
| Data stores | PostgreSQL with replication, encrypted storage and point-in-time recovery. Redis configured for both caching and the scheduler queue. | A database failover under load loses no committed payments. |
| Access and secrets | Change every default API key value, keep processor credentials and webhook secrets in a secrets manager, and put the Control Center behind staff networks and your identity provider where supported. | No default keys remain, and only named staff can change routing or credentials. |
| Observability | Route metrics, logs and traces through an OpenTelemetry collector into Prometheus, Loki and Tempo or your existing stack. Alert on authorization rate per processor, latency, errors and webhook backlog. | A processor outage alerts before customers report it. |
Hyperswitch operating ownership
Payments orchestration touches engineering, payments operations, security and finance. Each needs a defined role.
Platform team
- Runs the cluster, databases and proxies.
- Applies releases and database migrations.
- Tests failover and restores.
Payments operations
- Owns routing rules and connector settings.
- Watches authorization rates per processor.
- Handles disputes and processor escalations.
Security and compliance
- Owns vault key custody and access reviews.
- Maintains PCI DSS evidence with the QSA.
- Reviews Control Center roles.
Finance
- Works reconciliation exceptions.
- Tracks processing costs per processor.
- Signs off settlement totals.
Hyperswitch implementation questions
Does self-hosting change our PCI DSS obligations?
It can, because the orchestrator and possibly the vault run in your environment. The outcome depends on your card data path, segmentation and volumes. Confirm scope and assessment type with your QSA and acquirer; DeployOpen supports readiness work but does not issue reports on compliance.
How do upgrades work?
Hyperswitch publishes frequent tagged releases. Read the release notes for API, configuration and migration changes, rebuild custom connectors, test in staging against processor sandboxes, then roll out with Helm. Keep Control Center and SDK versions compatible with the router.
Which licenses apply?
The core platform, card vault, encryption service, Control Center, web SDK and Helm charts are Apache-2.0 according to their repositories. Check the license of every repository you deploy, including newer standalone services. Third-party vaults and processors have their own commercial terms.
Scope and handover
Effort depends on the number of processors and payment methods, whether card data is vaulted in your environment, custom connector needs, the checkout channels, reconciliation sources, availability targets and the state of your PCI DSS program.
DeployOpen maps your payment flows, designs routing and vault architecture, deploys and hardens Hyperswitch in your infrastructure, configures connectors and webhooks, integrates checkout and ledger, sets up reconciliation and monitoring, and tests the payment lifecycle. Handover includes data flow diagrams for your QSA, the routing rule register, connector inventory, key custody procedure, failover and upgrade runbooks, and test records.
