Payments Flows

Open, Modular, Self-Hostable Payment Infrastructure

Juspay 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 translate 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:

Tokenize 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