DEV Community: aveeJ

How We Used Low-Level Design to Build Scalable Payment Integrations with Hyperswitch Prism

aveeJ — Sun, 27 Sep 2026 05:18:12 +0000

Adding your first payment connector is fun. Adding your second is where you find out whether you designed anything at all.

Every processor wants something different: a different URL, a different HTTP method, a different JSON shape, a different idea of what a "card" looks like. If each connector is a pile of one-off code, connector #2 is a copy-paste of connector #1, and connector #50 is a maintenance nightmare.

Hyperswitch Prism talks to 100+ connectors today. To keep that manageable, we used a handful of well-known design patterns. This post walks through them.

Meet Hyperswitch Prism

Hyperswitch Prism is a stateless Rust library that takes one unified payment request and turns it into the right API call for 100+ processors. The codebase is large, so the snippets in this post come from a condensed reference version of it (prism-lld-reference.rs). It has the same structure, with the details removed.

Here's the whole journey of one payment, and the map for the rest of this post:

Singleton (Creational Patterns)
    |
    |
 Request
    |
    |
Factory Method (Creational Patterns)
    |
    |
Strategy Pattern (Behavioral Patterns)
    |
    |
Adapter Pattern - Request (Structural Patterns)
    |
    |
Template Method (Behavioral Patterns)
    |
    |
Builder Method (Creational Patterns)
    |
    |
 HTTP Call
    |
    |
Adapter Pattern - Response (Structural Patterns)

Let's walk it top to bottom.

1. Singleton: set the config once, read it anywhere

Every part of the service needs config, but it should be loaded exactly once. We don't want to pass it through twenty function signatures, and we don't want a mutable global either.

static CONFIG: OnceLock<Arc<Config>> = OnceLock::new();

impl Config {
    pub fn init(host: String, port: u16) {
        let config = Config {
            server: Server { host, port },
        };

        CONFIG
            .set(Arc::new(config))
            .expect("Config already initialized");
    }

    pub fn instance() -> Arc<Config> {
        CONFIG
            .get()
            .expect("Config has not been initialized")
            .clone()
    }
}

OnceLock gives us "write once, read forever" with thread safety for free, and Arc makes handing it out cheap. If someone calls init twice, or reads the config before it's set, the program fails loudly instead of quietly running with the wrong settings.

2. Request: one shape for every payment

The merchant never speaks Adyen or Stripe. They send one unified request:

#[derive(Debug, Clone)]
pub struct PaymentRequest {
    pub amount: i64,
    pub currency: String,
    pub card_number: String,
}

    let payload = PaymentRequest {
        amount: 1000,
        currency: "EUR".to_string(),
        card_number: "4111111111111111".to_string(),
    };

Everything after this point is about turning that one shape into whatever the chosen connector wants.

3. Factory Method: from a name to a connector

Which connector to use is decided at runtime: it arrives as data, not as code. The factory turns that value into a real object:

impl ConnectorData {
    // Factory (Creational)
    // Here the factory is deciding which object to create based on the runtime value of connector
    fn get_connector_by_name(connector: ConnectorEnum) -> ConnectorData {
        match connector {
            ConnectorEnum::Adyen => Self {
                connector: Box::new(Adyen::new()),
                connector_name: connector,
            },
        }
    }
}

(Purists will point out that this is technically a "simple factory". The GoF Factory Method relies on subclasses overriding a creation method. The idea is the same: callers ask for a connector, and one place decides how to make it.)

Rust's match is exhaustive, so a new ConnectorEnum variant without a match arm doesn't compile.

4. Strategy: one contract, many connectors

Every connector implements the same trait, so the core doesn't need to know which one it's talking to:

// Strategy (Behavioral)
// Strategy interface
/*
                 ConnectorIntegrationV2
                       Strategy
                          |
              +-----------+-----------+
              |                       |
           Adyen                    Stripe
      Concrete Strategy        Concrete Strategy
*/
pub trait ConnectorIntegrationV2<Req>: ConnectorIntegrationAnyV2<Req> {
    fn get_http_method(&self) -> Method;

    fn get_url(&self) -> String;

And here's Adyen, one concrete strategy:

// concrete strategy
impl ConnectorIntegrationV2<PaymentRequest> for Adyen {
    fn get_http_method(&self) -> Method {
        Method::POST
    }

    fn get_url(&self) -> String {
        "https://api.adyen.io".to_string()
    }
}

Adyen supplies only two things: the HTTP method and the URL.

5. Adapter (request): speaking each connector's language

We know who we're talking to. Now we need to speak their language. Our unified PaymentRequest has to become the exact shape Adyen expects:

// Adapter (Structural) - Request
// Convert the unified request into the shape Adyen's API expects
impl TryFrom<&PaymentRequest> for AdyenPaymentRequest {
    type Error = String;
    fn try_from(req: &PaymentRequest) -> Result<Self, Self::Error> {
        if req.amount <= 0 {
            return Err("Amount must be positive".into());
        }
        Ok(Self {
            amount: AdyenAmount {
                value: req.amount,
                currency: req.currency.clone(),
            },
            merchant_account: "MyMerchantAccount".into(),
            payment_method: AdyenPaymentMethod {
                method_type: "scheme".into(),
                number: req.card_number.clone(),
            },
        })
    }
}

Adyen's quirks, like "scheme" for cards and a merchant_account field, live here and nowhere else. Validation lives here too, so bad input is rejected before we ever build an HTTP request. In the real codebase, these are the transformers.rs files that sit next to every connector.

6. Template Method: we own the steps, connectors fill the blanks

Who actually puts the request together? The trait does, through a default method:

    // Template Method (Behavioral)
    // Fixed skeleton; each connector fills in get_http_method and get_url
    fn build_requestv2(&self) -> Option<Request> {
        Some(
            // Builder (Creational)
            // Build a complex object step-by-step
            RequestBuilder::new()
                .method(self.get_http_method())
                .url(self.get_url())
                .build(),
        )
    }

The order of steps is written once and shared by every connector. Connectors only supply their own values. Changing how every request is built means changing one method, not 100 connectors.

7. Builder: assembling the request step by step

Rather than one constructor with a long list of arguments, the request is built one step at a time:

impl RequestBuilder {
    fn new() -> RequestBuilder {
        Self {
            method: Method::POST,
            url: String::new(),
        }
    }
    pub fn method(mut self, method: Method) -> Self {
        self.method = method;
        self
    }
    pub fn url(mut self, url: String) -> Self {
        self.url = url;
        self
    }
    fn build(self) -> Request {
        Request {
            method: self.method,
            url: self.url,
        }
    }
}

Each step is named, and unset values fall back to defaults (POST). In Prism, the same builder also sets headers, bodies and certificates.

8. Adapter (response): bringing the answer home

The request goes out, and Adyen replies in its own format. Before that reaches the merchant, we translate it back. It's the same Adapter, just running the other way.

Every connector's reply lands in one unified shape:

#[derive(Debug)]
pub enum PaymentStatus {
    Authorized,
    Failed,
}

#[derive(Debug)]
pub struct PaymentResponse {
    pub status: PaymentStatus,
    pub connector_transaction_id: String,
}

And Adyen's version of "it worked" gets mapped into it:

// Adyen-specific response (the shape Adyen's API returns)
#[derive(Debug)]
pub struct AdyenPaymentResponse {
    pub psp_reference: String,
    pub result_code: String,
}

// Adapter (Structural) - Response
// Convert Adyen's response back into the unified shape
impl TryFrom<AdyenPaymentResponse> for PaymentResponse {
    type Error = String;
    fn try_from(res: AdyenPaymentResponse) -> Result<Self, Self::Error> {
        let status = match res.result_code.as_str() {
            "Authorised" => PaymentStatus::Authorized,
            "Refused" => PaymentStatus::Failed,
            other => return Err(format!("Unknown resultCode: {other}")),
        };
        Ok(Self {
            status,
            connector_transaction_id: res.psp_reference,
        })
    }
}

Adyen says "Authorised", another processor says "succeeded", a third says "APPROVED", and the merchant sees Authorized in each case. Every connector has two adapters, one for the request and one for the response.

The small bit of Rust glue

A blanket impl gives every connector a way to return itself as a strategy object, with no extra code per connector:

impl<S, Req> ConnectorIntegrationAnyV2<Req> for S
where
    S: ConnectorIntegrationV2<Req>,
{
    fn get_connector_integrationv2(&self) -> BoxedConnectorIntegration<'_, Req> {
        Box::new(self)
    }
}

And supertraits let us describe a connector's capabilities as a stack:

pub trait ConnectorServiceTrait: PaymentAuthorizeV2 {}

pub trait PaymentAuthorizeV2: ConnectorIntegrationV2<PaymentRequest> {}

Want capture, refund or void? Add another trait to the stack. The compiler then checks that every connector implements all of them.

Putting it together

Here's the whole diagram as code:

pub fn process_internal_authorization(
    connector: ConnectorEnum,
    payload: PaymentRequest,
    config: Arc<Config>,
) -> Result<PaymentResponse, String> {
    println!(
        "Server running on {}:{}",
        config.server.host, config.server.port
    );

    // Selecting the strategy

    let connector_data = ConnectorData::get_connector_by_name(connector);

    // Strategy (Behavioral)

    let connector_integration_v2: BoxedConnectorIntegration<'_, PaymentRequest> =
        connector_data.connector.get_connector_integrationv2();

    // Adapter (Structural) - Request
    let connector_request = AdyenPaymentRequest::try_from(&payload)?;
    println!("{:?}", connector_request);

    // Template Method (Behavioral) + Builder (Creational)
    let request = connector_integration_v2.build_requestv2();
    println!("{:?}", request);

    // HTTP Call (mocked): pretend Adyen replied
    let connector_response = AdyenPaymentResponse {
        psp_reference: "8515131751004933".to_string(),
        result_code: "Authorised".to_string(),
    };

    // Adapter (Structural) - Response
    PaymentResponse::try_from(connector_response)
}

fn main() {
    // Singleton (Creational)
    Config::init("http://localhost".to_string(), 8080);
    let config = Config::instance();

    let payload = PaymentRequest {
        amount: 1000,
        currency: "EUR".to_string(),
        card_number: "4111111111111111".to_string(),
    };

    let response = process_internal_authorization(ConnectorEnum::Adyen, payload, config);
    println!("{:?}", response);
}

Run it, and each output line comes from a different step:

Server running on http://localhost:8080
AdyenPaymentRequest { amount: AdyenAmount { value: 1000, currency: "EUR" }, merchant_account: "MyMerchantAccount", payment_method: AdyenPaymentMethod { method_type: "scheme", number: "4111111111111111" } }
Some(Request { method: POST, url: "https://api.adyen.io" })
Ok(PaymentResponse { status: Authorized, connector_transaction_id: "8515131751004933" })

Singleton, then the request Adapter, then Template Method + Builder, then the response Adapter.

(Two simplifications: to keep the snippet short, this calls Adyen's adapters directly, and the HTTP call is mocked. In Prism, each connector owns its own transformations, so the core never names a specific connector, and the request really goes over the wire.)

The real test: connector #2

Here's Stripe's strategy:

pub struct Stripe;

// concrete strategy
impl ConnectorIntegrationV2<PaymentRequest> for Stripe {
    fn get_http_method(&self) -> Method {
        Method::POST
    }

    fn get_url(&self) -> String {
        "https://api.stripe.com".to_string()
    }
}

That's the whole strategy: two answers, same as Adyen. To finish the job, we'd add Stripe's two adapters (request and response), plus one variant and one match arm in the factory.

What we wouldn't touch: the Singleton, the unified Request, the Template Method, the Builder, or the orchestration function. On the diagram, only the Strategy and the two Adapter boxes get a new entry. Everything else stays exactly the same.

A new connector only adds code for what is specific to that processor.

Prism is open source, built in Rust, with SDKs across languages.

GitHub: github.com/juspay/hyperswitch-prism
Node.js: npm install hyperswitch-prism
Python: pip install hyperswitch-prism
Java: io.hyperswitch:prism on Maven Central
Docs: docs.hyperswitch.io/integrations/prism/prism/installation

If this was useful, a ⭐ on GitHub goes a long way. And if you've used a different pattern to tame connector sprawl, we'd love to hear about it in the comments.

From Authorization to Settlement: A Payment Is a Lifecycle

aveeJ — Mon, 29 Jun 2026 18:37:23 +0000

A payment isn't a thing you fetch. It's a thing that happens.

A card gets authorized in one request. The money gets captured in another, maybe
the next morning when the warehouse confirms stock. A refund shows up a week
later. A 3DS challenge parks the whole thing in a "waiting on the customer" limbo
that resolves in a browser tab your server never sees. Confirmations trickle in
by webhook, out of order, sometimes twice.

Most SDKs flatten all of that into a Payment object with a single status
field. That shape is convenient, and it's exactly where things start to go
wrong:

const payment = await sdk.payments.get(id)

if (payment.status === "succeeded") {
  await fulfillOrder(payment.order_id)   // looks fine, ships a bug
}

Here's the catch: "succeeded" isn't one thing. A succeeded authorization and a
succeeded capture are different events, and a success you polled for is different
again from one that turned up in a settlement webhook. Authorizing reserves the
money. Capturing actually moves it. So if you fulfill on the authorization,
you've shipped goods against a hold that can still be declined later, or just
quietly expire.

And the code passes review. The test card authorizes and captures in one go, so
the demo is green and everyone moves on. Then a real customer pays with a 3DS
card, the else branch fires on a payment that actually went through, and you're
debugging it in production.

Good SDKs hand you the whole lifecycle. The ones that don't give you a noun with
a status field, and let you write code that reads correctly and behaves wrong.

How Hyperswitch Prism models it

Prism doesn't hand you one mutable Payment to poke at. A payment has a
position in a state machine, with named flows instead of a single status. Its
PaymentStatus enum carries thirty-odd states, and they're grouped on purpose:

STARTED → AUTHENTICATION_PENDING → AUTHORIZED → CHARGED → (refund sub-process)
                  │                     │           │
            (3DS / SCA)          (money reserved)  (money moved)

The API mirrors that machine. There's no status setter sitting on an object.
The lifecycle shows up as verbs spread across a few clients, and every call tells
you where the payment ended up:

import {
  PaymentClient,                 // get / capture / refund / void
  MerchantAuthenticationClient,  // open the session, mint client token
  EventClient,                   // parse + verify asynchronous webhooks
  types,
} from "hyperswitch-prism"

await paymentClient.capture({ connectorTransactionId, /* ... */ })

Notice capture is its own method, not update({ status: "captured" }). You
can't fat-finger a capture onto a payment that was never authorized and have it
pass as a harmless-looking status string. The methods you can call are the
transitions you're actually allowed to make.

One word, three enums

A flat status field is a trap because "succeeded" turns up in three different
places that mean three different things. Prism gives each one its own type:

PaymentStatus.AUTHORIZED vs PaymentStatus.CHARGED — reserved vs moved.
Webhook events are a separate enum: PAYMENT_INTENT_AUTHORIZATION_SUCCESS vs PAYMENT_INTENT_CAPTURE_SUCCESS. Both say "success." Only one means you got paid.
Refunds get their own enum again: RefundStatus.REFUND_SUCCESS, with its own pending and failure states, because a refund is its own sub-process.

Cram all three into one status field and you're overloading it, and the
overloading is where the bug lives. Keep the flows apart and you read the one you
actually meant.

Two non-PCI flows, two shapes

"Non-PCI" means the sensitive part (the card number, the PayPal login) gets
entered in the connector's own client-side SDK and never reaches your server.
Your backend only ever holds tokens and ids. Prism supports this, but the
lifecycle looks different from one connector to the next, which is another reason
a flat status falls short. Take Adyen and PayPal:

NON-PCI: the card / login is entered in the connector's client SDK.
Your server only holds tokens and ids — never raw card data.

ADYEN  ·  authorize now, capture later, outcome via webhook
  Browser Drop-in        Your backend           Prism / UCS        Adyen
       │                      │                      │               │
       │  open session ──────►│ createClientAuth ───►│ ── /sessions ►│
       │ ◄─ clientToken ──────│ ◄────────────────────│ ◄─ session ───│
       │                      │                      │               │
       │  card entered in Drop-in, authorized client-side ──────────►│
       │                      │ ◄═══ AUTHORISATION webhook ══════════│
       │                      │ EventClient.handleEvent (verify HMAC)│
       │                      │ record pspReference                  │
       │  complete checkout ─►│ authorizePayment                     │
       │                      │   polls verified outcome (~12s)      │
       │ ◄── AUTHORIZED ──────│   capture is a SEPARATE call later   │
       ▼                      ▼                      ▼               ▼

PAYPAL  ·  approve in popup, then auto-capture server-side
  Browser Buttons        Your backend           Prism / UCS        PayPal
       │                      │                      │               │
       │  open session ──────►│ create order ───────►│ ── /orders ──►│
       │ ◄─ orderId ──────────│ ◄────────────────────│ ◄─ orderId ───│
       │                      │                      │               │
       │  buyer approves in popup (no card on server) ─────────────►│
       │  complete checkout ─►│ authorizePayment                     │
       │                      │   PaymentClient.authorize            │
       │                      │   paypalSdk token + AUTOMATIC ──────►│ capture
       │ ◄── CAPTURED ────────│ ◄────────────────────│ ◄─ CHARGED ───│
       ▼                      ▼                      ▼               ▼

With Adyen, the card is authorized inside the Drop-in, and the result only
reaches your server by webhook. So authorizePayment can't just read a status.
It waits for the verified event, then picks up the pspReference from that
webhook as the transaction id, which it needs for the capture you run separately:

// initiate: hand the browser a client token; the card stays client-side
const session = await authClient.createClientAuthenticationToken({ /* amount */ })
// → { clientToken, publishableKey }  — server never sees the card

// authorize: the outcome only exists once the verified webhook lands
const outcome = getWebhookOutcome(sessionId)   // recorded by EventClient
// → AUTHORIZED + pspReference   (capture is a later, separate call)

PayPal works the other way around. The order is created up front, the buyer
approves it in the popup, and your server captures the approved order in one shot
with AUTOMATIC capture:

// initiate: create the order server-side, hand the browser its id
const orderId = await createPaypalOrder({ /* amount, currency */ })
// → buyer approves orderId in the PayPal popup; no card on your server

// authorize: capture the approved order using the JS-SDK token
const res = await paymentClient.authorize({
  paymentMethod: { paypalSdk: { token: { value: orderId } } },
  captureMethod: types.CaptureMethod.AUTOMATIC,
})
// → CHARGED   (already captured; only refunds remain)

Same vocabulary, two real paths. Adyen ends on AUTHORIZED with a capture still
owed; PayPal ends on CHARGED right away. A plain status field would call both
of those "succeeded" and hide the fact that one of them still needs a capture.
The named states won't let that slip.

Truth that isn't synchronous

Sometimes the answer isn't there yet when you ask for it. In client-side flows
the authorization decision lands later, over a webhook, so a synchronous read is
really just a guess. Prism treats it as a guess rather than pretending
otherwise:

A status read with nothing behind it yet comes back PENDING, not ERROR. Unknown means "check again in a bit," not "decline someone who already paid."
An async event has to prove itself before it can move state. EventClient parses the webhook, checks the source, and only then maps it. A webhook it can't verify is just a forged transition, so it gets rejected, and there's no dev-mode shortcut around that.
Even the amount isn't a plain number. It's a currency-scaled minor unit, so 1000 is ¥1000 in one currency and $10.00 in another.

The takeaway

Treat a payment as a lifecycle and a few habits follow:

Don't branch on one status. Ask the specific question: authorized, captured, or refunded? They're different flows.
Treat a sync read as provisional. Default unknowns to pending and let the verified event settle it.
Never fulfill on authorization. Only a capture means you've been paid.
Money is a currency-scaled integer, not a number.

A payment runs from authorization to settlement, and treating it as a lifecycle
rather than a single status is the gap between code that works and code that only
looks like it does. Prism puts the
lifecycle in front of you, with separate verbs, separate flows, and events it
actually verifies, so the obvious thing to write tends to be the right thing too.

Reference: Hyperswitch Prism on GitHub