Hyperswitch architecture

A 30,000 feet view of Hyperswitch's architecture
This chapter will help you quickly understand the Hyperswitch application's architecture

At high level, Hyperswitch has two main components,
  • router, which handles the incoming requests and talks to various connectors.
  • a low latency storage layer

Core API Layer

The "Core" is the unifying layer of Hyperswitch, which handles the incoming requests, authenticates, intelligently picks the connector(s) and processes the payments or refunds on behalf of the merchant.
The incoming requests could be from merchant servers, the client SDK, or webhooks from the connectors. The core layer also contains other business intelligence like the connector routing logic.


Hyperswitch treats external services as connectors. The connectors could be payment processors like stripe, paypal or fraud/risk prevention services like signifyd, or any other payment services.
The "Connector" module is a light weight stateless service, that contains the necessary logic to convert the hyperswitch payments data into a format required by the payment processor, connects to the appropriate endpoints, sends the requests, interprets the response, and provides the final status and message back to the Core.
This module is constructed as a stateless service and hence fully decoupled from the Core. This allows the Core to communicate with the diverse payment processor integrations and helps separate the detail-oriented data transformation layer from the Core.
The Core communicates with Connector through a standard interface abstracted to carry the payment use case and respective payment data.


Persistence with consistency is quite crucial for a transactional system like Hyperswitch. However, the storage layer should not become a bottleneck for a high-performance application. The critical path of a payment lifecycle primarily characterizes frequent read and write to a record (lasting for a few minutes), post which the record is frequent read and rarely written (lasting up to 6 months).
Hence, to ensure a high-performance system for processing peak transaction volumes, the storage is further divided into three sub-parts:
  • Cache layer to de-bottleneck the persistent (SQL) storage by exposing data essential for high-frequency read-write operations.
  • Persistent (SQL) storage for ensuring persistence and consistency
  • write-back / drainer to write back the data to SQL storage layer for persistence and consistency.
The router can still read data from SQL storage as necessary.
Last modified 2mo ago