Hyperswitch Prism

Hyperswitch Prism：一站式支付处理器集成与统一连接库

在当今全球化的商业环境下，集成多个支付处理器（Payment Processor）已成为企业的核心需求。然而，不同供应商如 Stripe、Adyen、Braintree 和 Worldpay 的 API 规范、错误代码及身份验证方法各不相同，这给开发者带来了巨大的复杂性。Hyperswitch Prism 正是为了解决这一痛点而生的开源解决方案。

什么是 Hyperswitch Prism？

Hyperswitch Prism 是一个无状态的、统一的支付连接器库，旨在通过单一的集成接口连接任何支付处理器。它是从经过多年实战检验、被全球领先商户使用的 Juspay Hyperswitch 支付平台中提取而出的核心组件。

核心定位：Prism 是一个轻量级、零锁定、开发者友好的支付库。它将复杂的支付处理器差异抽象化，让开发者可以用几行代码轻松切换不同的支付供应商。

为什么支付处理器集成如此困难？

每一个支付处理器都有其独特的 API 行为、文档规范以及在沙盒环境与生产环境之间的差异。微小的错误或疏忽都可能对企业的收入造成重大财务影响。Hyperswitch Prism 的出现，将这些分散在各大企业的“部落知识”转化为一个标准化的开源库，使支付集成像使用数据库驱动程序一样简单。

Hyperswitch Prism 的核心功能与特性

Hyperswitch Prism 具备以下关键特性，使其在支付集成领域脱颖而出：

1. 统一的请求模式（One Request Schema）

无论您是调用 Stripe 还是 Adyen，所有的支付授权请求都使用相同的 Schema。这意味着您无需为不同的供应商编写冗余的适配代码，即可实现统一的 authorize 调用。

2. 完全无状态（Stateless Architecture）

Hyperswitch Prism 不包含数据库，也不存储任何 PII（个人身份信息）。支付凭据仅在 HTTP 客户端的生命周期内存在，库本身不会记录或存储任何敏感信息。这种设计确保了极高的安全性和系统轻量化。

3. 显著减少 PCI 合规范围

开发者可以自主选择是否让卡片数据流经该库。您可以利用支付处理器的 Vault，或者使用您自有的 PCI 认证 Vault。由于 Prism 不存储任何数据，它能有效帮助企业降低 PCI 合规的复杂度。

4. 多语言 SDK 支持

为了满足不同开发团队的需求，Hyperswitch Prism 提供了多种主流编程语言的 SDK，包括：

• Node.js
• Python
• Java / Kotlin
• Rust

Hyperswitch Prism 的应用场景 (Use Case)

场景一：全球支付路由优化

企业可以根据交易币种、地理位置或费率，动态地在不同支付处理器之间切换。例如，在处理美元（USD）交易时使用 Stripe，而在处理欧元（EUR）交易时切换到 Adyen，这一切只需更改一行配置代码即可实现。

场景二：支付冗余与故障转移

当某个支付处理器发生服务中断时，利用 Hyperswitch Prism 的统一接口，系统可以迅速将流量切换到备份处理器，确保业务连续性而不必重写核心支付逻辑。

场景三：降低供应商锁定风险（Zero Lock-in）

通过使用 Prism 作为转换层，企业不再被绑定在单一的支付供应商身上。这种灵活性使得商户在商务谈判中更具优势，并能快速响应市场变化。

如何使用 Hyperswitch Prism

1. 安装库

根据您的开发语言，选择相应的安装方式：

• Node.js: npm install hyperswitch-prism
• Python: pip install hyperswitch-prism
• Java/Kotlin (Maven): 在 pom.xml 中添加依赖：

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

2. 发起支付授权请求 (Node.js 示例)

以下是如何使用 Hyperswitch Prism 调用 Stripe 进行支付授权的简单示例：

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

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

const main = async () => {
    let client = new PaymentClient(config);
    let request = {
        merchantTransactionId: "authorize_123",
        amount: { minorAmount: 1000, 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,
    };
    let response = await client.authorize(request);
    if (response.status === types.PaymentStatus.CHARGED) {
        console.log("支付成功");
    }
};
main();

3. 实现支付路由逻辑

通过简单的逻辑判断，即可实现处理器的动态路由：

// 根据币种选择处理器：EUR -> Adyen, USD -> Stripe
const config = currency === types.Currency.EUR ? adyenConfig : stripeConfig;
const client = new PaymentClient(config);
// 后续调用统一的 authorize 方法

开发与平台支持

Hyperswitch Prism 的核心由 Rust 编写（要求 Rust 1.70+），保证了极高的性能和类型安全性。目前支持的平台架构包括：

• macOS (Apple Silicon): arm64
• Linux: x86_64

如果您正在使用 AI 助手进行开发，可以访问 llm/llm.txt 获取完整的 SDK 参考文档，包含安装、错误处理、字段探测等详细信息。

常见问题解答 (FAQ)

Q: Hyperswitch Prism 提供内置的卡券库（Vault）吗？ A: 不提供。这是一个有意的设计选择。Prism 专注于支付转换层，您可以自带 Vault 或使用支付处理器的 Tokenization 服务。

Q: Prism 是否支持自动重试或智能路由逻辑？ A: Prism 仅作为转换层存在。重试和复杂的路由逻辑由 Juspay Hyperswitch 平台提供。Prism 的目标是保持轻量化和无状态。

Q: Prism 支持哪些支付处理器？ A: 目前支持包括 Stripe、Adyen、Braintree、Worldpay、Nuvei、PayPal 在内的多种主流处理器。具体的覆盖程度请参考官方文档中的 Connector Coverage。

Q: 它是否包含订阅、反欺诈或税务计算功能？ A: 目前 Prism 专注于支付流。未来，我们的目标是将其演进为一个无状态的商务库，逐步覆盖订阅、欺诈检测和税务等领域。