一次看懂hyperswitch-prism支付方式：Card、Apple Pay、Google Pay、PayPal、Klarna全覆盖

hyperswitch-prism 是一个面向多支付处理器的统一支付方式集成库：用同一个authorize请求结构，就能对接 Stripe、Adyen、PayPal、Klarna 等数十个 connector。Card 卡支付、Apple Pay 与 Google Pay 钱包、PayPal 跳转、Klarna 先买后付（BNPL），全部只需切换payment_method字段。本文带你一次看懂 hyperswitch-prism 支持的主流支付方式及其背后的关键概念。

为什么需要统一的支付集成库？

每个支付处理器（payment processor）的 API、错误码、认证方式和文档行为都各不相同，一处疏忽就可能造成真实资金损失。hyperswitch-prism 从生产级支付平台 Juspay Hyperswitch 中抽取而来，把多年踩坑经验沉淀为一个轻量库，核心优势有三点：

• 一个请求结构：同一个authorize调用适用于 Stripe、Adyen 等众多处理器，无需为每家重写逻辑
• 无状态、零锁定：无数据库、不存储 PII，凭据只存在于 HTTP 客户端生命周期内
• 降低 PCI 范围：卡数据是否流经你的服务器完全由你决定

更多背景可阅读项目根目录的 README.md。

支付方式全景：一张表看懂

Prism 的authorize请求接受一个payment_method对象，描述买家的支付工具。每个对象里只设置一个变体，Prism 负责完成 connector 特定的转换。完整清单见 payment-methods/README.md：

Card 卡支付：最基础的请求结构

Card 是最直接的支付方式：商户直接收集卡号、有效期、CVC 并传给 Prism。一个典型的 Node.js 请求如下（完整示例见 card.md）：

const response = await paymentClient.authorize({ merchantTransactionId: "txn_001", amount: { minorAmount: 1000, currency: Currency.USD }, paymentMethod: { card: { cardNumber: { value: "4111111111111111" }, cardExpMonth: { value: "03" }, cardExpYear: { value: "2030" }, cardCvc: { value: "737" }, }, }, captureMethod: CaptureMethod.AUTOMATIC, });

⚠️PCI 提示：卡数据直传需要商户自行满足 PCI 合规。如果卡信息是通过 Stripe.js、Adyen Drop-in 等处理器 JS SDK 在浏览器端采集并 tokenize 的，则应改用tokenAuthorize()+ 顶层connector_token字段，原始卡数据完全不经过你的服务器。两种方式对比详见 connector-token.md。

Apple Pay 集成：加密 token 的两种解密路径

Apple Pay 使用客户 Apple Wallet 中的 token 化卡片。流程是：客户端通过 Apple Pay JS API（或原生 SDK）完成支付 sheet，拿到PKPaymentToken对象，再把其中的paymentData（base64 加密数据）、paymentMethod和transactionIdentifier原样传入payment_method.apple_pay——加密数据永远不需要手工构造。

关键在于 token 的解密路径由商户 connector 账户配置决定（详见 apple-pay.md）：

• PSP 解密（SkipDecryption）：加密 blob 封给处理器证书，原样透传，由处理器在授权时用 Apple 支付处理证书解密
• Hyperswitch 解密（DecryptAtApplication）：blob 封给 Hyperswitch 证书，在授权前解密，处理器收到的是 DPAN、有效期和在线支付密码（cryptogram）

Google Pay 集成：token 类型决定谁来解密

Google Pay 与 Apple Pay 思路一致：在浏览器中初始化 Google Pay API、调用loadPaymentData()，取出paymentMethodData.tokenizationData.token传入payment_method.google_pay。

区别在于tokenizationSpecification.type决定了 token 加密给谁（详见 google-pay.md）：

• PAYMENT_GATEWAY：token 加密给处理器的网关密钥，原样转发，处理器自行解密——整个会话仅凭已存储的 connector 钱包配置拼装，不额外调用 Google
• DIRECT/INTERNAL_GATEWAY：token 加密给 Hyperswitch 控制的密钥，授权前验证并解密：CRYPTOGRAM_3DS得到带密码和 ECI 的 DPAN，PAN_ONLY得到真实卡 PAN

PayPal 钱包支付：跳转认证只需一个 email

PayPal 是典型的跳转式钱包支付：调用payment_method.paypal_redirect（可带上客户 email），Prism 返回跳转地址，客户到 PayPal 完成认证并批准付款，随后被带回你的return_url。整个过程商户不接触任何卡信息，请求结构非常简单（见 paypal.md）。

Klarna 先买后付（BNPL）：托管跳转流程

Klarna 属于 Buy Now Pay Later（先买后付）：客户选择分期或延后付款，Klarna 负责信贷决策。Prism 通过return_url把客户重定向到 Klarna 的托管流程，请求里甚至只需要一个空的payment_method.klarna对象；偏好语言、账单信息等 connector 专属选项可经connectorFeatureData传入（见 klarna.md）。

其他支付方式速览

除上述五种主打方式外，Prism 还覆盖：

• 在线银行跳转：如 iDEAL（荷兰客户在自家银行页面完成付款，无需卡信息）
• 直接借记：如 SEPA（凭 IBAN 从欧元区银行账户代扣）、ACH（美国账户代扣）
• 券 / 现金、加密货币、礼品卡等：完整字段清单见 payment-methods/README.md

💡 换处理器不换请求：无论底层是 Stripe 还是 Adyen，Card、Apple Pay 等所有支付方式共用同一套请求结构，只需切换 connector 配置，这就是"几行代码扩展新处理器"的含义。

快速上手：三步发起第一笔支付

1. 安装 SDK（Node.js 为例，Python / Java / Rust 同理）：npm install hyperswitch-prism
2. 配置 connector（以 Stripe 为例）并创建PaymentClient
3. 调用authorize()，按上文切换payment_method即可覆盖不同支付方式

各语言 SDK 指南：sdk/python、sdk/javascript、sdk/java、sdk/rust；完整可运行的 Stripe + Adyen 电商示例见 demo/e-commerce。

完整文档与多语言示例在哪里找

• 📚 支付方式文档：docs/getting-started/payment-methods/
• 📖 全量 connector 能力矩阵：docs/generated/connectors/ 与 all_connector.md
• 🧩 各 connector 的 TS / Python / Kotlin / Rust 示例：examples/
• 🔌 API 服务参考：docs/generated/api-reference/services/

常见问题

问：卡数据会经过我的服务器吗？答：用card直传时会（需 PCI 合规）；改用connector_token或钱包支付则不会，库本身不存储、不记录任何卡数据。

问：Apple Pay / Google Pay 的 token 谁来解密？答：由payment_method对应的 connector 配置决定：封给处理器的 token 原样透传、由 PSP 解密；封给 Hyperswitch 的则先在授权前解密再下发。

问：接入多个处理器要重写多少代码？答：请求结构完全一致，切换处理器只是换 connector 配置。业务路由、智能重试等编排逻辑属于上层平台（Juspay Hyperswitch）的范畴，Prism 专注转换层。