Payments Suite

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