什么是 Prism？

Prism 是一个无状态的统一连接器库，用于连接任何支付处理器。它提取自经过多年使用中的持续测试和迭代修复而强化的集成，源自 Juspay Hyperswitch。

为什么支付处理器集成如此重要？

每个支付处理器都有多样的 API、错误代码、认证方法、需要阅读的 pdf 文档，以及实际环境与文档规范之间的行为差异。

一个小的错误或疏忽可能会对接受支付的企业造成巨大的财务影响。全球成千上万的企业已经经历了这一学习曲线，并在许多年里迭代和修复了支付系统。所有这些修复/改进/迭代都作为部落知识锁定在企业支付平台和 SaaS 支付编排解决方案中。

因此，Prism - 旨在以简单、轻量、零锁定、开发者友好的支付库形式，向全世界开放支付多样性。

Prism 由 Juspay Hyperswitch 背后的团队提取、构建和维护 - 这是一个拥有 40K+ Github 星标的开源支付平台，被全球领先的企业主商户使用。

注意： 诚实地说，支付并不比数据库驱动程序更复杂。只是该行业尚未达到标准（而且永远不会达到！！）。

Prism 擅长做什么？

• 统一的请求模式 适用于所有支付。相同的授权调用可适用于 Stripe、Adyen 以及更多平台，无需额外代码。
• 无状态。无数据库，不存储 PII。 库不存储/记录凭证。其生命周期仅与您的 HTTP 客户端相同。
• 缩小 PCI 范围。 卡片数据是否流入库由您决定。您可以选择利用任何支付处理商的保险库或您自己的 PCI 认证保险库。库不记录或存储任何内容。

集成 - 状态

Prism 支持多个连接器，具有不同级别的支付方式和流程覆盖范围。每个连接器都会针对真实的沙箱/生产环境进行持续测试。

图例： ✓ 支持 | x 不支持 | ⚠ 进行中 | ? 需要验证

状态	描述
✓	已完全实现并测试
x	不适用或处理器不支持
⚠	实现进行中或部分完成
?	实现需要针对生产环境进行验证

查看完整的连接器覆盖范围 →

Prism 目前不做什么？

• 内置保险库或令牌化服务。 这是一个设计选择。您可以自带保险库，或使用支付处理商的保险库。
• 重试或路由逻辑。 它位于 Juspay Hyperswitch。Prism 仅作为转换层。
• 支付之外。 多样性存在于支付之外——在订阅、欺诈、税务、付款中。而我们的愿景，是将 Prism 演进为一个无状态的商业库。

架构

Prism 架构和组件的高层概览。要了解更多信息 请参阅文档

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

---

🚀 快速开始

在集成之前，请阅读对应语言的 SDK 指南——其中涵盖了连接器认证配置、各连接器的必填字段、沙盒测试卡片、状态码以及常见的运行时陷阱。

语言	SDK 集成指南
Python	sdk/python/README.md
Node.js	sdk/javascript/README.md
Java	sdk/java/README.md
Rust	sdk/rust

演示应用：查看 E-Commerce Demo 以获取包含 Stripe 和 Adyen 集成的完整可运行示例。

安装 Prism 库

首先，使用您选择的语言安装该库。

Node.js

npm install hyperswitch-prism

Python

pip install hyperswitch-prism

Java/Kotlin

添加到你的 pom.xml：

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

有关详细安装说明，请参阅 安装指南。

---

进行支付

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()

🤖 使用 AI 助手构建

如果你正在使用 AI 助手进行构建，请指向 curl 以获取完整的 SDK 参考：

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

此文件包含完整的 SDK 文档，包括安装、支付操作、错误处理、连接器配置、字段探测数据以及所有支付处理器的示例。

🔄 在支付提供商之间进行路由

一旦基本管道实现完毕，您就可以利用 Prism 的核心优势——通过更改一行代码来切换支付提供商。

  // 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

您可以仅将客户端替换为任何业务规则和用于支付处理器路由的智能重试逻辑。每个流程都使用相同的统一架构，无论底层处理器的 API 存在何种差异。

如果您希望了解更多关于路由逻辑和智能重试的信息，您可以查看 intelligent routing 和 smart retries。它有助于配置和管理多样化的支付受理设置，并提高转化率。

---

🔌 插件

针对主流平台的现成集成。

平台	包	描述
Medusa	@juspay-tech/medusa-custom-payments	Medusa v2 后端支付提供商
Medusa	@juspay-tech/medusa-custom-payments-react	React 店面结账组件

---

🛠️ 开发

前置条件

• Rust 1.70+
• Protocol Buffers (protoc)

从源码构建

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

# Build
cargo build --release

# Run tests
cargo test

Grace 工作区（TypeScript 仪表盘 + 检查点引擎）

对于 grace/ TypeScript 工作区（对等性仪表盘、AI 辅助连接器集成），使用以下命令进行初始化：

make grace-workspace

如果必要，此操作会通过 corepack 自动安装 pnpm，然后运行完整的先决条件探测、安装、构建以及交互式 .env 脚手架。有关完整的设置说明，包括 LLM 认证模式（Anthropic OAuth、裸 API 密钥、LiteLLM 网关）和运行器选择（claude-code 与 opencode），请参阅 grace/grace-workspace/README.md。

不想在主机上安装 Node + claude + gh？请改用容器化路径：make grace-workspace-docker 会构建一个自包含的镜像，并通过 docker-compose 启动 supervisor + dashboard + opencode-serve 边车。需要导出 TENXGRACE_PROJECT_ROOT。完整的先决条件和限制条件见工作区 README 中的“Docker (alternative entry)”部分。

---

💻 平台支持

hyperswitch-prism SDK 包含针对以下平台和架构编译的平台特定原生库。

平台	架构
macOS (Apple Silicon)	arm64
Linux	x86_64

报告漏洞

请将安全问题报告至 security@juspay.in。