DOCSEARCHbyAlgolia
Submit Docs

Hyperswitch Payments Infrastructure

repository·main·Indexed 12 days ago

https://github.com/juspay/hyperswitch

An open-source, composable payments infrastructure built in Rust. Hyperswitch enables developers to build modular payment stacks with intelligent routing, vaulting, and revenue recovery, or connect to over 100+ payment processors. The ecosystem includes components such as the Router, Scheduler, Drainer, and an analytics pipeline utilizing Kafka, Clickhouse, and OpenSearch.

Tokens
140K
Snippets
563
Records
775
Agent score
99%

What's inside Hyperswitch

  1. Overview of the Drainer application

    main
    The Drainer is a specialized application within the Hyperswitch ecosystem designed to process data from Redis streams. Its primary function is to read incoming stream data and execute corresponding queries against the database, acting as a bridge between real-time event streams in Redis and persistent storage.

  3. Understand Dashboard routes and availability

    main

    The Hyperswitch dashboard provides several management routes.

    Local Development Access:

    • Docker Compose: The dashboard is served by Nginx from website/dist at http://localhost:8081/dashboard/.
    • Vite (Source-run): If running via Vite, routes are mounted at http://localhost:5173/.

    Production Hosting:

    • The preferred route for external production hosting is /decision-engine/.
    • API traffic should be proxied through /decision-engine-api/*.

    Available Dashboard Routes:

    • /dashboard/ (Home)
    • /dashboard/login
    • /dashboard/signup
    • /dashboard/onboarding
    • /dashboard/routing
    • /dashboard/routing/sr
    • /dashboard/routing/rules
    • /dashboard/routing/volume
    • /dashboard/routing/debit
    • /dashboard/decisions
    • /dashboard/analytics
    • /dashboard/audit

  4. Use the Cards crate for card masking and validation

    main
    The cards crate provides specialized types designed to handle sensitive card data. It is primarily used for implementing card masking (obfuscating sensitive digits) and performing card validation logic within the Hyperswitch ecosystem.

  5. Use API Models for router crate requests and responses

    main
    The api_models crate provides the standardized request and response data structures used by the router crate. Developers building integrations or extending the router should use these models to ensure compatibility with the Hyperswitch API surface.

  6. What is the Decision Engine?

    main
    The Decision Engine is a standalone Rust service that acts as an intelligent layer between your orchestrator and payment gateways. It evaluates eligible gateways for every payment and selects the optimal one based on rules, live success rates, or cost. Because it runs independently over HTTP, it does not require a mandatory orchestrator, preventing vendor lock-in.

  7. What is Multi-Objective Routing?

    main

    Multi-objective routing is a cost-aware post-step layered on top of Success-Rate (SR) scoring. While standard SR routing optimizes for the highest authorization rate, multi-objective routing balances authorization rate and processing cost to maximize the merchant's economic outcome (Expected Value).

    How it works:

    1. The SR scorer runs first to produce a ranking based on authorization probability.
    2. A post-step attaches per-gateway fee estimates to these candidates.
    3. The engine re-ranks candidates based on Expected Value (EV): Economic value (EV) = auth rate × settlement value where settlement value = txn amount − cost of payment processing.

    This approach preserves all standard SR features (dimension-level buckets, elimination, hedging) but applies cost as an additional lens at the end of the decision process.

  8. Overview of Hyperswitch Payment Modules

    main

    Hyperswitch is a modular payments infrastructure. Instead of a monolithic integration, you can pick and integrate specific modules based on your needs:

    • Cost Observability: Tools to audit and optimize payment costs, detecting hidden fees and penalties.
    • Revenue Recovery: Intelligent retry strategies (tuned by card bin, region, etc.) to combat passive churn.
    • Vault: A PCI-compliant service for storing cards, tokens, and wallets. Supports 'bring-your-own-vault' (e.g., VGS, TokenEx).
    • Intelligent Routing: Routes transactions to the PSP (e.g., Stripe, Adyen, Braintree) with the highest predicted authorization rate.
    • Reconciliation: Automates 2-way and 3-way reconciliation with customizable outputs.
    • Alternate Payment Methods: Drop-in widgets for PayPal, Apple Pay, Google Pay, Samsung Pay, Pay by Bank, and BNPL (e.g., Klarna).

  9. Understand the Decision Engine API access classes

    main

    The Decision Engine API is organized into different access classes based on the required permissions and authentication methods. Use the following guide to determine how to authenticate your requests:

    • Public: No authentication required. Used for health checks and initial onboarding.
      • Routes: GET /health, GET /health/ready, GET /health/diagnostics, POST /auth/signup, POST /auth/login.
    • Admin bootstrap: Requires an Admin secret.
      • Routes: POST /merchant-account/create.
    • Protected: Requires either a JWT token via Authorization: Bearer <jwt_token> or an API key via x-api-key: <api_key>. This covers most operational routes including routing, decisions, rule configuration, and analytics.
    • Sandbox: Any route served through https://sandbox.hyperswitch.io. Follows the same authentication rules as Protected routes, but requires the additional header x-feature: decision_engine.

  11. Understand the Router crate architecture

    main

    The router crate is the main orchestrator of the Hyperswitch project. It is structured into several key functional areas:

    • core: Contains the central orchestration logic and common payment flows (e. ext{g.}$, customers, payment methods, payments, and refunds). Connector-specific implementations should remain minimal and reside in the connector module.
    • connector: Houses gateway-specific transformation implementations (e.g., adyen, stripe).
    • routes: Defines the API endpoints exposed by the router, currently implemented using actix_web.
    • types: Contains object and API type definitions, split into api (for the router API) and storage (for database interactions via Diesel).
    • configs: Handles configuration loading.
    • services: Manages external service integrations, such as redis.
    • scheduler: Manages scheduled tasks and related types.
    • utils: General utility functions.

  12. Use the Mock Server for payment processor APIs

    main

    The cypress-tests directory includes a router-based mock server (Express) to simulate payment processor APIs.

    Architecture:

    • mockserver.js: Entry point.
    • router.js: Central router.
    • Connector implementations (e.g., Silverflow.js): Individual router implementations.

    Running the Mock Server:

    • Start the server: npm run mockserver (Default port: 3010).
    • Custom port: MOCKSERVER_PORT=3010 npm run mockserver.

    Integrating with Hyperswitch: To redirect a specific connector's traffic to the mock server, set the corresponding environment variable in Hyperswitch. For example, to redirect Silverflow: ROUTER__CONNECTORS__SILVERFLOW__BASE_URL=http://localhost:3010/silverflow cargo r

    # Start mock server
npm run mockserver

# Run Hyperswitch with Silverflow redirected to mock server
ROUTER__CONNECTORS__SILVERFLOW__BASE_URL=http://localhost:3010/silverflow cargo r