Java SDK Overview

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

Status	Description
✓	Fully implemented and tested
x	Not applicable or unsupported by processor
⚠	Implementation in progress or partial
?	Implementation needs validation against live environment

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.

Installation

Maven

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

Gradle

implementation 'io.hyperswitch:prism:1.0.0'

Quick Start

import com.hyperswitch.prism.PaymentClient;
import java.util.Map;
import java.util.HashMap;

PaymentClient paymentClient = PaymentClient.builder()
    .connector("stripe")
    .apiKey("YOUR_API_KEY")
    .environment("SANDBOX")
    .build();

// Build amount
Map<String, Object> amount = new HashMap<>();
amount.put("minorAmount", 1000);
amount.put("currency", "USD");

// Build card details
Map<String, Object> cardDetails = new HashMap<>();
cardDetails.put("cardNumber", Map.of("value", "4242424242424242"));
cardDetails.put("cardExpMonth", Map.of("value", "12"));
cardDetails.put("cardExpYear", Map.of("value", "2027"));
cardDetails.put("cardCvc", Map.of("value", "123"));
cardDetails.put("cardHolderName", Map.of("value", "John Doe"));

// Build payment method
Map<String, Object> paymentMethod = new HashMap<>();
paymentMethod.put("card", cardDetails);

// Build request
Map<String, Object> request = new HashMap<>();
request.put("merchantTransactionId", "txn_order_001");
request.put("amount", amount);
request.put("paymentMethod", paymentMethod);
request.put("authType", "NO_THREE_DS");
request.put("captureMethod", "MANUAL");

// Authorize payment
Map<String, Object> response = paymentClient.authorize(request);
System.out.println(response.get("status")); // AUTHORIZED

Services

Service	Description
Payment Service	Process payments from authorization to settlement
Recurring Payment Service	Manage subscriptions and recurring billing
Refund Service	Retrieve and track refund statuses
Dispute Service	Handle chargebacks and disputes
Event Service	Process webhook notifications
Payment Method Service	Store and manage payment methods
Customer Service	Manage customer profiles
Merchant Authentication Service	Generate access tokens
Payment Method Authentication Service	3D Secure authentication
Payout Service	Send funds to recipients

Configuration

Option	Type	Required	Description
connector	String	Yes	Payment connector name (stripe, adyen, etc.)
apiKey	String	Yes	Your API key
environment	String	Yes	SANDBOX or PRODUCTION
timeout	Duration	No	Request timeout (default: 30s)

Error Handling

try {
    Map<String, Object> response = paymentClient.authorize(request);
} catch (PaymentDeclinedException e) {
    // Handle declined payment
    System.err.println("Payment declined: " + e.getMessage());
} catch (ValidationException e) {
    // Handle validation error
    System.err.println("Validation error: " + e.getErrors());
} catch (HyperswitchException e) {
    // Handle other errors
    System.err.println("Error: " + e.getMessage());
}

Support

For support and documentation, visit https://docs.hyperswitch.io