juspay/hyperswitch-prism

What is Prism?

Prism is a stateless, unified connector library to connect with any payment processor. It is extracted out of the hardened integrations through continuous testing & iterative bug fixing over years of usage within Juspay Hyperswitch.

Why are payment processor integrations such a big deal?

Every payment processor has diverse APIs, error codes, authentication methods, pdf documents to read, and behavioural differences between the actual environment and documented specs.

A small mistake or oversight can create a huge financial impact for businesses accepting payments. Thousands of enterprises around the world have gone through this learning curve and iterated and fixed payment systems over many years. All such fixes/improvements/iterations are locked-in as tribal knowledge into Enterprise Payment Platforms and SaaS Payment Orchestration solutions.

Hence, Prism - to open up payment diversity to the entire world as a simple, lightweight, zero lock-in, developer friendly payments library.

Prism is extracted, built and maintained by the team behind Juspay Hyperswitch - the open-source payments platform with 40K+ Github stars and used by leading enterprise merchants around the world.

Note: In all honesty, payments are not more complicated than database drivers. It is simply just that the industry has not arrived at a standard (and it never will!!).

What does Prism do well?

• One request schema for every payment. The same authorize call works against Stripe, Adyen and many more without additional lines of code.
• Stateless. No database, no stored PII. Credentials are not stored/ logged by the library. It lives only up to the lifetime of your HTTP client.
• PCI scope reduction. The card data flowing/ not flowing into the library is your choice. You can choose to leverage any payment processor vault or your own PCI certified vault. Nothing is logged or stored by the library.

Integrations - Status

Prism supports multiple connectors with varying levels of payment method and flow coverage. Each connector is continuously tested against real sandbox/ production environments.

Legend: ✓ Supported | x Not Supported | ⚠ In Progress | ? Needs Validation

View Complete Connector Coverage →

What Prism does not do (yet)?

• Built-in vault or tokenization service. This is a design choice. You may bring your own vault, or use the payment processor's vault.
• Retry or routing logic. It lives in Juspay Hyperswitch. Prism is only the transformation layer.
• Beyond payments. The diversity exists beyond payments - in subscriptions, fraud, tax, payouts. And it is our aspiration, to evolve Prism into a stateless commerce library.

Architecture

A very high level overview of the Prism architecture and components. To understand more refer docs

┌─────────────────────────────────────────────────────────────────┐
│                        Your Application                         │
└───────────────────────────────┬─────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                         Prism Library                           │
│     (Type-safe, idiomatic interface, Multi-language SDK)        │
└────────────────────────────────┬────────────────────────────────┘
                                 │
                                 ▼
         ┌───────────────────────┼───────────────────────┬───────────────────────┐
         ▼                       ▼                       ▼                       ▼
   ┌──────────┐           ┌──────────┐           ┌──────────┐           ┌──────────┐
   │  Stripe  │           │  Adyen   │           │ Braintree│           │ + more   │
   └──────────┘           └──────────┘           └──────────┘           └──────────┘

🚀 Quick Start

Before integrating, read the SDK guide for your language — it covers connector authentication configs, required fields per connector, sandbox test cards, status codes, and common runtime pitfalls.

Language	SDK Integration Guide
Python	sdk/python/README.md
Node.js	sdk/javascript/README.md
Java	sdk/java/README.md
Rust	sdk/rust

Demo Application: Checkout the E-Commerce Demo for a complete working example with Stripe and Adyen integration.

Install the Prism Library

Start by installing the library in the language of your choice.

Node.js

npm install hyperswitch-prism

Python

pip install hyperswitch-prism

Java/Kotlin

Add to your pom.xml:

<dependency>
    <groupId>io.hyperswitch</groupId>
    <artifactId>prism</artifactId>
    <version>0.0.4</version>
</dependency>

For detailed installation instructions, see Installation Guide.

Make a Payment

Node.js

import { PaymentClient, types, IntegrationError, ConnectorError } from 'hyperswitch-prism';

let config: types.ConnectorConfig = {
    connectorConfig: {
        stripe: {
            apiKey: { value: "sk_test_" }
        }
    }
}

const main = async () => {
    try {
        let client = new PaymentClient(config)
        let request: types.PaymentServiceAuthorizeRequest = {
            merchantTransactionId: "authorize_123",
            amount: {
                minorAmount: 1000, // $10.00
                currency: types.Currency.USD,
            },
            captureMethod: types.CaptureMethod.AUTOMATIC,
            paymentMethod: {
                card: {
                    cardNumber: { value: "4111111111111111" },
                    cardExpMonth: { value: "12" },
                    cardExpYear: { value: "2050" },
                    cardCvc: { value: "123" },
                    cardHolderName: { value: "Test User" },
                },
            },
            authType: types.AuthenticationType.NO_THREE_DS,
            address: {},
            orderDetails: [],
        }
        let response: types.PaymentServiceAuthorizeResponse = await client.authorize(request);
        switch (response.status) {
            case types.PaymentStatus.CHARGED:
                console.log("success");
                break;
            default:
                console.error("failed");
        }
    } catch (e: any) {
        //handle error
    }
  }

main()

🤖 Building with AI Assistants

If you are building with AI assistants, point at the curl to fetch the complete SDK reference:

curl -fsSL https://raw.githubusercontent.com/juspay/hyperswitch-prism/main/llm/llm.txt

This file contains complete SDK documentation including installation, payment operations, error handling, connector configuration, field probe data, and examples for all payment processors.

🔄 Routing between Payment Providers

Once the basic plumbing is implemented you can leverage Prism's core benefit - switch payment providers by changing one line.

  // Routing rule: EUR -> Adyen, USD -> Stripe
  const currency = types.Currency.USD;

  let stripeConfig: types.ConnectorConfig = {
      connectorConfig: {
          stripe: {
              apiKey: { value: process.env.STRIPE_API_KEY! }
          }
      }
  }

  let adyenConfig: types.ConnectorConfig = {
      connectorConfig: {
          adyen: {
              apiKey: { value: process.env.ADYEN_API_KEY! },
              merchantAccount: { value: process.env.ADYEN_MERCHANT_ACCOUNT! }
          }
      }
  }

  const config = currency === types.Currency.EUR ? adyenConfig : stripeConfig;
  const client = new PaymentClient(config);

  // Authorize call from previous step

You may just swap the client with any business rules and smart retry logic for payment processor routing. Each flow uses the same unified schema regardless of the underlying processor's API differences.

If you wish to learn more about routing logic and smart retries, you can checkout intelligent routing and smart retries. It can help configure and manage diverse payment acceptance setup, as well as improve conversion rates.

🔌 Plugins

Ready-made integrations for popular platforms.

🐳 Running the gRPC Server (Docker)

Prism also runs as a standalone gRPC server. Multi-arch images (linux/amd64, linux/arm64) are published to GitHub Container Registry on every nightly tag — browse the available tags. latest follows the most recent nightly; pin a dated tag for anything you need to reproduce.

docker run --rm -p 8000:8000 ghcr.io/juspay/hyperswitch-prism:latest

The server registers its own descriptors, so grpcurl needs no local .proto files — it can list the services and print the exact request schema:

grpcurl -plaintext localhost:8000 grpc.health.v1.Health/Check
# { "status": "SERVING" }

grpcurl -plaintext localhost:8000 list
grpcurl -plaintext localhost:8000 describe types.PaymentService.Authorize
grpcurl -plaintext localhost:8000 describe types.PaymentServiceAuthorizeRequest

Connector credentials are sent per request in the x-connector-config metadata header, as JSON of the form {"config":{"Stripe":{"api_key":"sk_test_..."}}} — it selects the connector and carries its credentials, and the server keeps neither. The proto definitions are in crates/types-traits/grpc-api-types/proto.

Configuration

The image ships development.toml (default), sandbox.toml and production.toml. Pick one with CS__COMMON__ENVIRONMENT:

docker run --rm -p 8000:8000 \
  -e CS__COMMON__ENVIRONMENT=sandbox \
  ghcr.io/juspay/hyperswitch-prism:latest

Individual keys are overridden with CS__<SECTION>__<KEY> environment variables, for example CS__SERVER__PORT=9000. To supply a config of your own, mount it over the one in the image:

docker run --rm -p 8000:8000 \
  -v "$(pwd)/my-config.toml:/app/config/development.toml:ro" \
  ghcr.io/juspay/hyperswitch-prism:latest

Metrics

Prometheus metrics are served on port 8080. Publish that port as well if you want to scrape them:

docker run --rm -p 8000:8000 -p 8080:8080 ghcr.io/juspay/hyperswitch-prism:latest
curl localhost:8080/metrics

The endpoint is empty until the server has handled its first request.

The image is also built with the OTLP push pipeline compiled in, disabled by default. Enable it to push metrics to an OpenTelemetry collector over gRPC:

docker run --rm -p 8000:8000 \
  -e CS__METRICS__OTEL__ENABLED=true \
  -e CS__METRICS__OTEL__OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317 \
  ghcr.io/juspay/hyperswitch-prism:latest

The endpoint must be an OTLP gRPC receiver (default port 4317). Enabling this does not affect the Prometheus endpoint above.

🛠️ Development

Prerequisites

• Rust 1.70+
• Protocol Buffers (protoc)

Building from Source

# Clone the repository
git clone https://github.com/juspay/hyperswitch-prism.git
cd hyperswitch-prism

# Build
cargo build --release

# Run tests
cargo test

Grace workspace (TypeScript dashboard + checkpoint engine)

For the grace/ TypeScript workspace (parity dashboard, AI-assisted connector integration), bootstrap with:

make grace-workspace

This auto-installs pnpm via corepack if needed, then runs the full prereq probe, install, build, and interactive .env scaffold. See grace/grace-workspace/README.md for the full setup story including LLM auth modes (Anthropic OAuth, bare API key, LiteLLM gateway) and runner choice (claude-code vs opencode).

Don't want Node + claude + gh on your host? Use the containerized path instead: make grace-workspace-docker builds a self-contained image and starts the supervisor + dashboard + opencode-serve sidecar via docker-compose. Requires TENXGRACE_PROJECT_ROOT exported. Full prereqs and limitations in the workspace README's "Docker (alternative entry)" section.

💻 Platform Support

The hyperswitch-prism SDK contains platform-specific native libraries compiled for following platforms and architectures.

Reporting Vulnerabilities

Please report security issues to [email protected].