DEV Community: Neeraj Kumar

Prism: A stateless payment integration library extracted from 4 years of production

Neeraj Kumar — Thu, 16 Apr 2026 15:40:55 +0000

The Problem

If you have ever integrated a payment processor, you know the drill. You read through a PDF that was last updated in 2019, figure out what combination of API keys goes in which header, discover that "decline code 51" means something subtly different on this processor than the last one you dealt with, and then do it all over again when your business decides to add a second processor.

We have been living in this world for years building Juspay Hyperswitch, an open-source and composable payments platform. At some point we had integrations for 100+ connectors. The integrations worked well — but they were locked inside our orchestrator, not usable by anyone who just needed to talk to Stripe or Adyen without adopting an entire platform.

And we always felt the payment APIs are not more complicated than database drivers. It is just that the industry has not arrived at a standard (and likely never will) for payments.

Hence, we decided to extract the integrations into a lightweight open interface for developers and AI agents to use, rather than recreate it every time.

This post is about how we did that: unbundling those integrations into a standalone library called Prism, and the engineering decisions we made along the way. Some of them are genuinely interesting.

Why unbundle at all?

The connector integrations inside Hyperswitch were not designed to be embedded in an orchestrator forever. They were always a self-contained layer: translate a unified request into a connector-specific HTTP call, make the call, translate the response back. The orchestrator was just the first thing to use them.

The more we looked at it, the more it seemed wrong to keep that capability locked behind a full platform deployment. If you just need to accept payments through Stripe, you should not have to adopt an orchestrator to get a well-tested, maintained integration. And if you want to switch to Adyen later, that should be a config change, not a rewrite.

So we separated the integration layer out. The result is a library with a well-defined specification — a protobuf schema covering the full payment lifecycle — that can be embedded directly in any application or deployed as a standalone service.

Why protobuf for the specification?

Q: JSON schemas exist. OpenAPI exists. Why protobuf?

The core requirement was multi-language client generation. We needed Python developers, Java developers, TypeScript developers, and Rust developers to all be able to consume this library with first-class, type-safe APIs — without anyone hand-writing SDK code in each language. Protobuf has the most mature ecosystem for this: prost for Rust, protoc-gen-java for Java, grpc_tools.protoc for Python, and so on. It also doubles as our gRPC interface description when the library is deployed as a server, which turned out to be a natural fit for the two deployment modes we wanted to support.

The specification covers the full payment lifecycle across nine services:

Service	What it does
`PaymentService`	Authorize, capture, void, refund, sync — the core lifecycle
`RecurringPaymentService`	Charge and revoke mandates for subscriptions
`RefundService`	Retrieve and sync refund statuses
`DisputeService`	Submit evidence, defend, and accept chargebacks
`EventService`	Process inbound webhook events
`PaymentMethodService`	Tokenize and retrieve payment methods
`CustomerService`	Create and manage customer profiles at connectors
`MerchantAuthenticationService`	Access tokens, session tokens, Apple Pay / Google Pay session init
`PaymentMethodAuthenticationService`	3DS pre/authenticate/post flows

Everything is strongly typed. PaymentService.Authorize takes a PaymentServiceAuthorizeRequest — amount, currency, payment method details, customer, metadata, capture method — and returns a PaymentServiceAuthorizeResponse with a unified status enum, connector reference IDs, and structured error details. No freeform JSON blobs. No stringly-typed status fields. The spec is the contract.

The implementation: Rust at the core

Q: Why Rust? Wouldn't Go or Java be simpler?

A few reasons. First, we already had 50+ connector implementations in Rust from Hyperswitch, so starting there was practical. But more importantly: the library needs to be embeddable in Python, JavaScript, and Java applications without a separate process or a runtime dependency like the JVM or a Python interpreter. The only realistic way to distribute a native library that loads cleanly into all of those runtimes is as a compiled shared library — .so on Linux, .dylib on macOS. Rust produces exactly that, with no garbage collector pauses, no runtime to ship, and memory safety that does not require a GC.

The Rust codebase is organized into a handful of internal crates:

connector-integration — The actual connector logic: 50+ implementations translating unified domain types into connector-specific HTTP requests and parsing responses back
domain_types — Shared models: RouterDataV2, flow markers (Authorize, Capture, Refund, ...), request/response data types
grpc-api-types — Rust types generated from the protobuf spec via prost
interfaces — The trait definitions that connector implementations must satisfy

The two-phase transformer pattern

The single most important design decision in the Rust core is that the library never makes HTTP calls itself. Every payment operation is split into two pure functions:

┌─────────────┐    req_transformer      ┌──────────────────┐
│  Unified    │ ──────────────────────▶ │ Connector HTTP   │
│  Request    │                         │ Request          │
│  (proto)    │                         │ (URL, headers,   │
└─────────────┘                         │  body)           │
                                        └────────┬─────────┘
                                                 │  you make this call
                                                 ▼
┌─────────────┐    res_transformer      ┌──────────────────┐
│  Unified    │ ◀────────────────────── │ Connector HTTP   │
│  Response   │                         │ Response         │
│  (proto)    │                         │ (raw bytes)      │
└─────────────┘                         └──────────────────┘

req_transformer takes your unified protobuf request and returns the connector-specific HTTP request — the URL, the headers, the serialized body. You make the HTTP call however you like. res_transformer takes the raw response bytes plus the original request and returns a unified protobuf response.

Q: Why not just have the library make the HTTP call for you?

Mostly because it makes the library genuinely stateless and transport-agnostic. It does not own any connection pools. It does not have opinions about TLS configuration, proxy settings, or retry logic. When this code runs inside a Python application, the Python application's httpx client handles the HTTP. When it runs inside the gRPC server, the server's client handles it. This also turns out to be quite testable — you can unit test transformers by feeding them request bytes and asserting on the resulting HTTP request structure, without standing up any network infrastructure.

Each flow is registered using a pair of Rust macros:

// Register the request transformer for the Authorize flow
req_transformer!(
    fn_name: authorize_req_transformer,
    request_type: PaymentServiceAuthorizeRequest,
    flow_marker: Authorize,
    resource_common_data_type: PaymentFlowData,
    request_data_type: PaymentsAuthorizeData<T>,
    response_data_type: PaymentsResponseData,
);

// Register the response transformer for the Authorize flow
res_transformer!(
    fn_name: authorize_res_transformer,
    request_type: PaymentServiceAuthorizeRequest,
    response_type: PaymentServiceAuthorizeResponse,
    flow_marker: Authorize,
    resource_common_data_type: PaymentFlowData,
    request_data_type: PaymentsAuthorizeData<T>,
    response_data_type: PaymentsResponseData,
);

The macros generate the boilerplate: connector lookup, trait object dispatch, RouterDataV2 construction, serialization. A new flow means adding the connector trait implementation and one pair of macro invocations. The code generator handles everything else.

Two ways to use it

We wanted the library to work both as an embedded SDK (loaded directly into your application process) and as a standalone gRPC service (deployed separately, called over the network). Same Rust core, same proto types, same API — two completely different deployment topologies.

┌──────────────────────────────────────────────────────────┐
│                    Your Application                      │
└─────────────────────┬────────────────────────────────────┘
                      │
         ┌────────────┴────────────┐
         ▼                         ▼
 ┌──────────────┐         ┌─────────────────┐
 │   SDK Mode   │         │   gRPC Mode     │
 │  (FFI/UniFFI)│         │ (Client/Server) │
 └──────┬───────┘         └────────┬────────┘
        │                          │
        │  in-process call         │  network call
        ▼                          ▼
 ┌──────────────────────────────────────────────┐
 │              Rust Core (Prism)               │
 │  req_transformer → [HTTP] → res_transformer  │
 └──────────────────────────────────────────────┘

Mode 1: The embedded SDK

In SDK mode, the Rust core compiles into a native shared library (.so / .dylib) and is exposed to host languages via UniFFI — Mozilla's framework for generating language bindings from Rust automatically. When your Python code calls authorize_req_transformer(request_bytes, options_bytes), that call crosses the FFI boundary directly into the Rust binary running in the same process.

Data crosses the language boundary as serialized protobuf bytes. This is intentional — every language already has a protobuf runtime, so there is no custom serialization protocol to maintain, and the byte interface is completely language-neutral.

Q: Does this mean I need to compile Rust to use the Python SDK?

For development, yes — you run make pack, which builds the Rust library, runs uniffi-bindgen to generate the Python bindings, and packages everything into a wheel. For production use, we ship pre-built binaries for Linux x86_64, Linux aarch64, macOS x86_64, and macOS aarch64 inside the wheel. The loader picks the right one at runtime. You install the wheel and never think about Rust again.

Mode 2: The gRPC server

In gRPC mode, the grpc-server crate runs as a standalone async service built on Tonic (Rust's async gRPC framework). It implements all nine proto services, accepts gRPC connections from any language's generated stubs, makes the connector HTTP calls internally, and returns unified proto responses over the wire.

The gRPC server calls the same Rust core transformers as the FFI layer — just from a different entry point. The transformation logic is literally the same code path.

Each language SDK ships both deployment modes:

sdk/python/
├── src/payments/           ← FFI-based embedded SDK
│   ├── connector_client.py
│   └── _generated_service_clients.py
└── grpc-client/            ← gRPC stubs for server mode

sdk/java/
├── src/                    ← FFI-based embedded SDK (JNA + UniFFI)
└── grpc-client/            ← gRPC stubs for server mode

sdk/javascript/
├── src/payments/           ← FFI-based embedded SDK (node-ffi)
└── grpc-client/            ← gRPC stubs for server mode

Q: When would you actually choose gRPC over the embedded SDK?

The embedded SDK is great when you have a single-language service and want zero network overhead — serverless functions, edge deployments, or situations where adding a sidecar is painful. The gRPC server shines in polyglot environments: if your checkout service is in Java, your fraud service is in Python, and your reconciliation job is in Go, deploying one gRPC server gives all of them a shared, consistent integration layer without each one shipping a native binary.

The important point is that the choice is not a migration — your PaymentServiceAuthorizeRequest looks identical in both modes. You change a config flag, not your application code.

	SDK (embedded)	gRPC (network)
Latency	Microseconds (in-process)	Milliseconds (network)
Deployment	Library inside your app	Separate service to run
Language support	Python, JS, Java/Kotlin, Rust	Any language with gRPC
Connector HTTP	Your app makes the calls	Server makes the calls
Best for	Serverless, edge, single-language	Polyglot stacks, shared infra

Code generation: the glue that holds it together

Prism supports many payment flows and many SDK languages. Hand-maintaining typed client methods for each flow in each language is exactly the kind of work that introduces drift and bugs. So we don't do it.

The code generator at sdk/codegen/generate.py reads two sources of truth and emits all the SDK client boilerplate automatically.

Q: What are the two sources of truth?

services.proto compiled to a binary descriptor — this tells the generator every RPC name, its request type, its response type, and its doc comment.

crates/ffi/ffi/src/services/payments.rs — this tells the generator which flows are actually implemented, by scanning for req_transformer! invocations.

The generator takes their intersection. A flow in proto but not implemented in Rust? Warning, skipped — we don't ship unimplemented APIs. A transformer in Rust with no matching proto RPC? Also a warning — the spec is the authority, not the implementation.

Running make generate produces typed client classes across all languages. For example, in Python:

class PaymentClient(_ConnectorClientBase):
    async def authorize(
        self,
        request: PaymentServiceAuthorizeRequest,
        options=None
    ) -> PaymentServiceAuthorizeResponse:
        """PaymentService.Authorize — Authorizes a payment amount on a payment method..."""
        return await self._execute_flow(
            "authorize", request, _pb2.PaymentServiceAuthorizeResponse, options
        )

And in Kotlin:

class PaymentClient(config: ConnectorConfig, ...) : ConnectorClient(config, ...) {
    fun authorize(
        request: PaymentServiceAuthorizeRequest,
        options: RequestConfig? = null
    ): PaymentServiceAuthorizeResponse =
        executeFlow("authorize", request.toByteArray(), PaymentServiceAuthorizeResponse.parser(), options)
}

Here is the full pipeline:

services.proto
    │
    ├── prost (Rust build.rs)      → grpc-api-types crate (Rust types)
    ├── grpc_tools.protoc          → payment_pb2.py (Python proto stubs)
    ├── protoc-gen-java            → Payment.java (Java/Kotlin proto stubs)
    ├── protoc (JS plugin)         → proto.js / proto.d.ts (JS proto stubs)
    └── protoc (binary descriptor) → services.desc
                                            │
payments.rs (transformer registrations) ───┤
                                            ▼
                                      generate.py
                                            │
        ┌───────────────────────────────────┼──────────────────────┐
        ▼                                   ▼                      ▼
_generated_ffi_flows.rs    _generated_service_clients.py    GeneratedFlows.kt
                           connector_client.pyi             _generated_connector_client_flows.ts


cargo build --features uniffi
    └── uniffi-bindgen
              ├── connector_service_ffi.py   (Python native bindings)
              ├── ConnectorServiceFfi.kt     (Kotlin/JVM native bindings)
              └── ffi.js                     (Node.js native bindings)

The practical result: add a new flow to services.proto, implement the transformer pair in Rust, run make generate — and every language SDK gets a typed, documented method for that flow. No one writes boilerplate by hand.

Walking through a real authorize call

Let's trace what actually happens when a Python application calls client.authorize(...) in SDK mode:

① App builds PaymentServiceAuthorizeRequest (protobuf message)

② PaymentClient.authorize() → _execute_flow("authorize", request, ...)

③ _ConnectorClientBase._execute_flow():

   a. request.SerializeToString() → request_bytes

   b. authorize_req_transformer(request_bytes, options_bytes)
      ──── FFI boundary: Python → Rust shared library ────
      Rust: build_router_data! macro
        ├── ConnectorEnum::from("stripe")   ← look up connector
        ├── connector.get_connector_integration_v2()
        ├── proto bytes → PaymentFlowData + PaymentsAuthorizeData
        ├── construct RouterDataV2 { flow, request, auth, ... }
        └── connector.build_request(router_data) → Request { url, headers, body }
      serialize Request → FfiConnectorHttpRequest bytes
      ──── returns bytes across FFI boundary ────

   c. deserialize FfiConnectorHttpRequest → url, method, headers, body

   d. httpx AsyncClient.post(url, headers=headers, content=body)
      ← this is the actual outbound HTTP call to Stripe

   e. raw response bytes received

   f. authorize_res_transformer(response_bytes, request_bytes, options_bytes)
      ──── FFI boundary: Python → Rust shared library ────
      Rust: connector.handle_response(raw_bytes)
        ├── parse Stripe's JSON response format
        └── map → PaymentServiceAuthorizeResponse (unified proto)
      serialize → proto bytes
      ──── returns bytes across FFI boundary ────

   g. PaymentServiceAuthorizeResponse.FromString(bytes)

④ App receives unified PaymentServiceAuthorizeResponse

In gRPC mode, steps ③b through ③f happen inside the grpc-server process. The app sends the protobuf request over the network and gets the protobuf response back. The connector lookup, HTTP call, and response transformation are identical — just running in a different process.

Where we go from here — together

We want to be upfront about what this is and what it is not.

What it is: a working implementation with 60+ connectors, a protobuf specification that covers the full payment lifecycle, and SDKs in four languages. It is ready to use today.

What it is not: a finished standard. The spec reflects our understanding of what payment integrations need to look like. That understanding is incomplete, and we know it. Payment APIs have a very long tail of edge cases — 3DS flows that differ between processors, webhook schemas that change without notice, authorization responses that technically succeeded but should be treated as soft declines. There is no team small enough to have seen all of it.

That is why community ownership matters here, not as a marketing posture, but as a practical necessity.

If you want to use it: install the SDK, run make generate to see what flows are available, and point it at your test credentials. When something breaks — and something will — open an issue. The more connectors and flows get exercised in real environments, the faster the rough edges get found.

If you want to contribute a connector: implement a Rust trait in connector-integration/. The FFI layer, gRPC server, and all language SDKs pick it up automatically. You do not need to write Python or JavaScript or maintain anything outside that one crate.

If you want to contribute a flow: start with a discussion on the services.proto shape — that is the community contract, so it deserves a conversation before code gets written. Once there is agreement, implement the transformer pair in Rust, run make generate, and every SDK gets the new method in every language.

If you disagree with a spec decision: open a discussion. The whole point of making this community-owned is that no single team's assumptions should be baked in permanently. If you have seen payment edge cases that the current schema cannot express, that is exactly the kind of feedback that shapes a standard.

The longer arc here is for services.proto to evolve into something the payments community — developers, processors, orchestrators, and everyone else in the stack — maintains collectively. The same way OpenTelemetry's semantic conventions emerged from broad input, not from one company's opinions. The same way JDBC worked because it was simple enough to implement and strict enough to actually abstract.

GitHub: juspay/hyperswitch-prism

Behind the Code: Planning Hacktoberfest at Hyperswitch

Neeraj Kumar — Thu, 26 Sep 2024 07:46:59 +0000

Ah, October—a time for pumpkin spice lattes, cozy sweaters, and… endless lines of code? That’s right, developers around the world gear up for Hacktoberfest, an exciting opportunity to flex their coding muscles and make meaningful contributions to open-source projects. Here at Hyperswitch, we’ve been prepping for this year’s Hacktoberfest like it's the Olympics of coding—except, you know, with more pull requests and fewer gold medals.

Let me take you behind the curtain to show you what goes into planning such a large-scale event. Spoiler alert: It involves a lot of coffee.

Stage 1: What Happened Last Year?

Before diving headfirst into this year’s event, we first ask ourselves the age-old question: What in the world happened last year? We dig into the data to see how many contributors we had, which trype of issues attracted the most pull requests, and, of course, whether or not we met our goals (or just managed to survive on caffeine alone).

For Hyperswitch, last year’s event was a hit—our community grew, and developers were happy. But we also noticed some areas where we could improve, like making the onboarding process a bit more newbie-friendly. Because, let’s be honest, jumping into open-source for the first time can feel a bit like learning to swim by being tossed into the deep end.

Stage 2: Understanding What is Required this year

Once we’ve dusted off the past, it’s time to set this year’s targets. How many new contributors do we want? Which issue types should we shine a spotlight on?

At Hyperswitch, we’re focusing on Dev Ex problems that could benefit 1000s of Developers. We’re also keeping a close eye on making sure first-time contributors feel welcome, because nothing says “We love open-source!” like crystal-clear documentation and an easy-to-follow roadmap.

Stage 3: Coordinate, Coordinate, Coordinate

Remember that thing your parents always said about teamwork? Well, Hacktoberfest planning is like that, but with a lot more Slack messages and Google Docs. I had to work closely with our design team to get the landing page live—because first impressions matter, and if it looks good, people will want to stay (kinda like a good dating profile, but for developers).

And, of course, the pièce de résistance—t-shirts and stickers! Why do we pour so much love into these goodies? Simple: validation. Because who doesn’t love being rewarded for their hard work with something they can wear proudly at their next dev meetup? It’s like the developer equivalent of a superhero cape.

Stage 4: Fix, Fix, Fix

Even the best-laid plans can hit a snag—or three. This stage is about fixing those last-minute hiccups, whether it’s resolving landing page bugs, updating contribution guidelines, or rewriting an issue to make it sound less like a riddle. (Nobody likes cryptic instructions, right?)

For all the freshers out there, don’t be scared of this stage! Fixing small bugs, improving documentation, or just suggesting tiny tweaks is a great way to get started. Trust me, you’ll feel like a wizard when your first pull request gets merged. Plus, you’ll walk away with some swag and the satisfaction of contributing to something bigger than yourself.

Why Hacktoberfest?

Why do I love Hacktoberfest? Well, besides the obvious fact that it’s a free pass to live in our IDEs for a month for Devs, it’s all about building community for me. It’s an open invitation to developers around the world to step up, contribute, and get some recognition. (Not to mention a sweet t-shirt to flex at your next virtual conference.)

For us at Hyperswitch, Hacktoberfest is also a way to give back to the open-source community that powers so much of what we do. Whether you’re an open-source veteran or still figuring out how to fork a repo, we want you to join in. Who knows? You might just build the next Instagram!

How you can Get Involved

Ready to jump in and make your mark during Hacktoberfest? Head over to our Hacktoberfest landing page [Don’t forget to share some feedback here], where you’ll find beginner-friendly issues, no code developments, and feature requests that need your touch.

Plus, we’ve got some shiny new plugins developments [Paid “$” Contributions] and integrations in the works that are ripe for contribution. Think of it as your chance to be the hero of our open-source saga.

Wrapping It Up

Planning Hacktoberfest is no small feat. From reflecting on last year to setting this year’s goals and coordinating every little detail, it’s a labor of love. But when the community comes together, it’s all worth it. We’re pumped to see what this year’s event brings and can’t wait to welcome developers of all experience levels to our open-source ecosystem.

Join our Community: Discord | Slack

Don’t forget to Star us on GitHub

Yeah, I know—I’m using GPT to write this. Don’t sweat it; the robots haven’t taken over just yet. But trust me, when they do, they’ll be fully equipped to take over the world!