Payments Suite

Open, Modular, Self-Hostable Payment Infrastructure

Hyperswitch is built for teams that want engineering-grade control over payments.

To simplify architectural decisions, the ecosystem can be viewed as four independent building blocks. By defining ownership of each block — Hyperswitch-managed, self-hosted, or third-party — you can design an architecture aligned with your compliance posture, performance requirements, and internal engineering capabilities.

The Four Core Components

The SDK (Frontend) :

The entry point for your payment flow. It resides in your frontend and is responsible for securely capturing sensitive payment information.

Intelligent Routing & Orchestration (Backend) :

The core of the operation. It manages the payment lifecycle, executes routing logic, and handles post-payment operations like refunds.

Acquirer & Processor Connectivity (Connectors) :

The actual pipelines that translates the transaction (e.g., Stripe, Adyen, Worldpay).

Vault (Card Data Storage) :

The secure locker for sensitive card data to enable "One-Click" recurring payments without the user re-entering details.

Each Component can be handled by Hyperswitch, managed or self-deployed by your own team, or even sourced from a third-party provider e.g. Vault (reference)

---

Integration Architecture

With the components defined, the next step is to select your integration architecture. This choice hinges on a single question: Who controls the payment execution ?

Choose the integration method that best aligns with your payment flow requirements:

Integration Model 1: Client-Side SDK Payments

(Tokenize Post-Payment | SDK-Initiated Execution)

When to Choose This Model

• You want dynamic, frontend-driven payment experiences

• You prefer minimal backend orchestration logic

• You want SDK-triggered payment confirmation

• You are optimizing for rapid checkout implementation

High-level Flow

1. Merchant will call the /payments API and load the Payment SDK.

2. SDK securely collects payment details.

3. SDK triggers payment confirmation.

4. SDK communicates with Hyperswitch backend.

5. Hyperswitch:

   • Applies routing logic

   • Sends request to configured PSP

   • Manages authorization/capture

   • Returns final payment status

---

Integration Model 2: Server-to-Server (S2S) Payments

(Tokenize Pre-Payment | Backend-Controlled Execution)

When to Choose This Model

• You want granular control over transaction timing

• You require backend-driven orchestration logic

• You want to tokenize credentials before execution

• You prefer decoupling vaulting from transaction processing

High-level Flow

Tokenisze Card :

• Tokenize payment credentials using - Vault SDK or backend call to /payment-methods

• Hyperswitch securely stores the credential and returns a reusable identifier - payment_method_id.

Trigger Payment Execution :

• Option A: Process via Hyperswitch Orchestration by calling /payments API.

  • Use this option if you want Hyperswitch to:

    • Apply routing logic

    • Select the optimal connector

    • Manage retries and failover

    • Handle authorization and capture lifecycle

    This is the recommended model for merchants adopting Hyperswitch orchestration.

• Option B: Process via Proxy API by calling /proxy API.

  • Use this option if:

    • You do not want to change your existing PSP integration immediately

    • You want Hyperswitch to act as a passthrough layer

    • You are incrementally migrating to full orchestration

    In this mode:

    • Your existing integration contract remains unchanged

    • Hyperswitch forwards requests to the configured processor

    • You can progressively enable routing and orchestration features