hyperswitch-prism

May 11, 2026 · View on GitHub

Hyperswitch Prism — Java/Kotlin SDK

A high-performance, type-safe Java/Kotlin SDK for payment processing through Hyperswitch Prism. Connect to 100+ payment processors through a single, unified API.

Features

🚀 High Performance — Direct UniFFI FFI bindings to Rust core via JNA
🔌 100+ Connectors — Single SDK for all major payment processors
☕ Kotlin/Java Native — Full Kotlin bindings with Java interop
⚡ Connection Pooling — Built-in HTTP connection pooling via OkHttp
🛡️ Type-Safe — Protobuf-based request/response serialization
🔧 Configurable — Per-request or global configuration for timeouts, proxies, and auth

🤖 For AI Assistants

Use curl to fetch the 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 100+ connectors.

AI Assistant Context

This SDK is part of Hyperswitch Prism — a unified connector library for payment processors.

What This SDK Does

Request Transformation: Converts unified payment requests to connector-specific formats
Response Normalization: Transforms connector responses back to a unified schema
Error Handling: Provides consistent error types (IntegrationError, ConnectorError, NetworkError) regardless of connector

Architecture

Your Java/Kotlin App
       │
       ▼
┌──────────────────────────────────────────────────────────────┐
│  Service Clients (PaymentClient, CustomerClient, etc.)       │
└───────────────────────────┬──────────────────────────────────┘
                            │
                            ▼
┌──────────────────────────────────────────────────────────────┐
│  ConnectorClient (OkHttp connection pool + HTTP execution)   │
└───────────────────────────┬──────────────────────────────────┘
                            │
                            ▼
┌──────────────────────────────────────────────────────────────┐
│  JNA/UniFFI Bindings (connector_service_ffi shared lib)      │
└───────────────────────────┬──────────────────────────────────┘
                            │
                            ▼
┌──────────────────────────────────────────────────────────────┐
│  Rust Core (connector transformation logic)                  │
└───────────────────────────┬──────────────────────────────────┘
                            │
                            ▼
              Payment Processor APIs

Key Files

File	Purpose
`src/main/kotlin/com/hyperswitch/payments/`	Public API (clients, types, errors)
`src/main/kotlin/com/hyperswitch/payments/ConnectorClient.kt`	HTTP execution layer with OkHttp
`src/main/kotlin/com/hyperswitch/generated/`	UniFFI-generated bindings
`src/main/proto/`	Protobuf message definitions

Package & Import

Package Name: io.hyperswitch:prism
Installation: Gradle/Maven dependency (see below)
Import: import com.hyperswitch.payments.*

Installation

Gradle (Kotlin DSL)

implementation("io.hyperswitch:prism:0.0.6")

Gradle (Groovy DSL)

implementation 'io.hyperswitch:prism:0.0.6'

Maven

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

Requirements:

JDK 17+
Rust toolchain (for building native bindings from source)

Platform Support:

✅ macOS (x64, arm64)
✅ Linux (x64, arm64)
✅ Windows (x64)

Quick Start

1. Configure the Client

import com.hyperswitch.payments.*
import com.hyperswitch.payments.generated.*

// Configure connector identity and authentication
// See SDK reference for specific authentication patterns per connector
val config = ConnectorConfig(
    connectorConfig = // Configure your connector (e.g., stripe, adyen, etc.)
)

// Optional: Request defaults for timeouts
val requestConfig = RequestConfig(
    http = HttpConfig(
        totalTimeoutMs = 30000,
        connectTimeoutMs = 10000
    )
)

2. Process a Payment

val client = PaymentClient(config, requestConfig)

val authorizeRequest = PaymentServiceAuthorizeRequest(
    merchantTransactionId = "txn_order_001",
    amount = Amount(
        minorAmount = 1000,
        currency = Currency.USD
    ),
    captureMethod = CaptureMethod.AUTOMATIC,
    paymentMethod = PaymentMethod(
        card = CardPaymentMethod(
            cardNumber = SecretString(value = "4111111111111111"),
            cardExpMonth = SecretString(value = "12"),
            cardExpYear = SecretString(value = "2027"),
            cardCvc = SecretString(value = "123"),
            cardHolderName = "John Doe"
        )
    ),
    address = Address(billingAddress = AddressDetails()),
    authType = AuthenticationType.NO_THREE_DS,
    returnUrl = "https://example.com/return",
    orderDetails = emptyList()
)

val response = client.authorize(authorizeRequest)
println("Status: ${response.status}")
println("Transaction ID: ${response.connectorTransactionId}")

Service Clients

Client	Purpose	Key Methods
`PaymentClient`	Core payment operations	`authorize()`, `capture()`, `refund()`, `void()`
`CustomerClient`	Customer management	`create()`
`PaymentMethodClient`	Secure tokenization	`tokenize()`
`MerchantAuthenticationClient`	Auth token management	`createServerAuthenticationToken()`, `createServerSessionAuthenticationToken()`, `createClientAuthenticationToken()`
`EventClient`	Webhook processing	`handleEvent()`
`RecurringPaymentClient`	Subscription billing	`charge()`
`PaymentMethodAuthenticationClient`	3DS authentication	`preAuthenticate()`, `authenticate()`, `postAuthenticate()`

Authentication

All credentials use SecretString wrapper for security:

SecretString(value = System.getenv("API_KEY"))

See the SDK reference for complete connector authentication patterns:

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

Advanced Configuration

Proxy Settings

val proxyConfig = RequestConfig(
    http = HttpConfig(
        proxy = ProxyConfig(
            httpsUrl = "https://proxy.company.com:8443",
            bypassUrls = listOf("http://localhost")
        )
    )
)

Per-Request Overrides

val response = client.authorize(request, RequestConfig(
    http = HttpConfig(
        totalTimeoutMs = 60000
    )
))

Connection Pooling

Each client instance maintains its own connection pool. For best performance:

// Create client once, reuse for multiple requests
val client = PaymentClient(config, defaults)

for (payment in payments) {
    client.authorize(payment)
}

Error Handling

import com.hyperswitch.payments.*

try {
    val response = client.authorize(request)
} catch (e: IntegrationError) {
    // Request-phase error (auth, URL construction, serialization, etc.)
    println("Code: ${e.errorCode}")
    println("Status: ${e.statusCode}")
    println("Message: ${e.message}")
} catch (e: ConnectorError) {
    // Response-phase error (deserialization, transformation, etc.)
    println("Code: ${e.errorCode}")
    println("Status: ${e.statusCode}")
    println("Message: ${e.message}")
}

Error Codes

Code	Description
`CONNECT_TIMEOUT`	Failed to establish connection
`RESPONSE_TIMEOUT`	No response received from gateway
`TOTAL_TIMEOUT`	Overall request timeout exceeded
`NETWORK_FAILURE`	General network error
`INVALID_CONFIGURATION`	Configuration error
`CLIENT_INITIALIZATION`	SDK initialization failed

Architecture

Your App → Service Client → ConnectorClient → UniFFI FFI (JNA) → Rust Core → Connector API
                ↓
         Connection Pool (OkHttp)

The SDK uses:

UniFFI — FFI bindings to Rust via JNA
protobuf-java — Protocol buffer serialization
OkHttp — High-performance HTTP client with connection pooling

Building from Source

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

# Build native library, generate bindings, and pack
make pack

# Run tests
make test-pack

# With live API credentials
STRIPE_API_KEY=sk_test_xxx make test-pack

How it works

make build-lib — builds crates/ffi/ffi with --features uniffi
make generate-bindings — runs uniffi-bindgen --language kotlin to produce generated/connector_service_ffi.kt
make generate-proto — runs protoc --java_out to produce Java protobuf stubs (callable from Kotlin)
make pack-archive — runs ./gradlew jar and copies the JAR to artifacts/sdk-java/