Hyperswitch 开源支付平台

它是什么

Hyperswitch 是 Juspay 做的开源支付栈，用 Rust 写成。你的收银台只调用一个 Hyperswitch API，Hyperswitch 再把每笔付款交给某个支付处理商，比如 Stripe、Adyen、Braintree、Worldpay 或 Checkout.com。README 说它能连接一百多家处理商。围绕这个核心，有几个相互独立的模块：在处理商之间做路由、重试失败的付款、卡片保险库、查看付款成本的视图、对账，以及其他支付方式。你只取需要的模块，其余不用管。README 称它是商业化的开源支付栈，仓库在 GitHub 上的描述也提到 SaaS 和自托管两种方式。这个条目讲的是这个仓库，以及怎么自己运行它。

1. 你的收银台带着付款调用 Hyperswitch API
2. 路由规则选出一个处理商，比如 Stripe 或 Adyen
3. 处理商批准或拒绝这笔付款
4. 重试规则可以把失败的付款再试一次
5. 结果回到你的收银台

适合谁

接收银行卡付款、想自己掌握收银台和处理商之间那一层的团队。README 点出三种常见的起点：只接了一个 Stripe 或 Braintree 的商户改成接多个处理商；商户用直连收单机构换掉原来的支付网关；还有的重建自己的支付平台，同时保留已经在用的保险库，比如 VGS 或 TokenEx。自托管那页文档还提到，想在自己场地内掌控的银行和支付机构也适合。

如果你只需要通过一个处理商收几笔银行卡付款，可能用不着它。自托管会让你成为一套支付系统的运维者，要管它的数据库、密钥和升级。

用在哪里

README 和 Juspay 的文档写了这些途径。

• 一键 Docker 脚本，在你自己的电脑上用 Docker 或 Podman
• 普通的 Docker Compose，来自本地安装页
• 在 Kubernetes 上用 Helm chart，README 说可以部署到 AWS、GCP 或 Azure
• 托管沙盒 https://app.hyperswitch.io，不用安装：Helm chart 页面说在那里注册，Exploration Guide 说登录后跑第一笔交易
• 网页、Android、iOS、React Native 和 Flutter 的客户端 SDK，用来把收银台放进你自己的网站或应用

README 的生态章节还列出一个 Terraform 仓库 hyperswitch-suite，说它是完整栈的推荐起点。工具包没有覆盖它。

如何设置

点“获取”会把一个装有 Mindket 安装说明的 zip 压缩包存进你的下载文件夹，里面有 Docker、Helm、沙盒和网页 SDK 这几条路线的步骤。主要途径是 README 里的一键 Docker 脚本。

1. 运行下面三行命令。它们来自 README，在终端里运行。
2. 输入 1、2 或 3 选一个配置。选项 1 Standard 标着 Recommended。
3. 等各项服务启动。脚本也会检查它们的健康状态。
4. 看它打印的链接。选 Standard 或 Full Stack 时，Control Center 在 http://localhost:9000。App Server 在 http://localhost:8080。就算健康检查失败了，脚本也会打印这些链接，所以要自己再确认。
5. 登录 Control Center。选 Standard 或 Full Stack 时，用脚本打印的演示邮箱和密码。

git clone --depth 1 --branch latest https://github.com/juspay/hyperswitch
cd hyperswitch
scripts/setup.sh

Juspay 的本地安装页给了一条更朴素的途径，不用脚本，也没有配置可选。

git clone https://github.com/juspay/hyperswitch
cd hyperswitch
docker compose up -d

如何使用

脚本最后会打印每项服务监听的地址。README 把 Control Center 描述成商户仪表盘，管连接器、路由规则、分析和 API 密钥。App Server 是你的收银台要调用的 API。README 给的下一步是在 Control Center 里添加一个支付连接器，再测试一笔付款。

想手动检查服务器的话，本地安装页给了下面这一行。它说返回 200 OK，就表示服务器和它的数据库、Redis 都在正常工作。

curl --head --request GET 'http://localhost:8080/health'

脚本会打印你所选配置对应的停止命令。Standard 和 Standalone 的是下面这一条，脚本发现的是 Podman 时，docker compose 换成 podman compose。

docker compose down

Full Stack 的是这一条。

docker compose --profile scheduler --profile monitoring --profile olap --profile full_setup down

示例

你开了一家店，只通过一个处理商收款，想再备好一个。你在笔记本上的仓库文件夹里运行脚本，输入 1 选 Standard 配置：

scripts/setup.sh

脚本会打印 Control Center 的地址 http://localhost:9000，以及演示用的邮箱和密码。你登录后，给每个处理商各加一个连接器，在它们之间设好路由，再试一笔付款。README 说托管沙盒能看到日志、路由规则和重试策略，所以你可以先在那里走一遍同样的步骤。

新手与专家

新手：支付处理商是替银行卡付款转钱的公司。Hyperswitch 不是处理商。它夹在你的收银台和处理商之间，决定每笔付款交给哪一家。连接器就是 Hyperswitch 和某一家处理商之间的那条连接。最简单的起点是托管沙盒，什么都不用装。你要先在那里注册或登录。接着运行 Standard 配置，加一个连接器，发一笔测试付款。等这一步走通了，再去看保险库和 Helm 途径。

专家：README 把整个项目拆成几项服务。这个仓库里的 Rust 应用服务器是核心，它依赖一个卡片保险库和一个加密服务。旁边还有两个独立的项目。hyperswitch-prism 是面向支付处理商的统一连接器库，decision-engine 是路由控制平面，可以配合任何编排器使用。

在 Kubernetes 上，整套系统来自 hyperswitch-stack 这个 chart。下面是 chart 页面给的命令。

helm repo add hyperswitch https://juspay.github.io/hyperswitch-helm
helm repo update
kubectl create namespace hyperswitch
helm install hypers-v1 hyperswitch/hyperswitch-stack -n hyperswitch

chart 页面说卡片保险库和它的依赖默认会装上。但要它能保存卡片，你还得生成主密钥和保管人密钥（custodian keys），并用它们打开 locker。工具包列出了这几步。

贡献指南说 Hyperswitch 大量用到 feature，所以常用的 cargo 命令要多带一个参数。格式化要用 nightly 工具链。

cargo check --all-features
cargo clippy --all-features
cargo test --all-features
cargo +nightly fmt

注意事项

这是支付软件，运行它就意味着你要对它存放的东西负责。

• 不是 Juspay 写的说明：工具包由 Mindket 编写。Hyperswitch 是 Juspay 做的，这些说明不是 Juspay 写的，也没有得到它的认可
• 卡片数据：README 称保险库符合 PCI。自托管那页文档说，你自己托管时，要完全负责自己的 PCI DSS 认证和数据处理
• 脚本会往外发什么：它会调用一个辅助脚本，把 Hyperswitch 的版本和安装状态发到 hyperswitch.gateway.scarf.sh。失败时还会发出失败的命令和错误日志的最后一行。脚本最先运行这个辅助脚本，早于其他任何步骤，并且带着 set -Eeuo pipefail，所以如果这个请求连不上（断网或被拦截），脚本会停在它的错误处理那一步。脚本没有关掉这一步的开关，所以先读 scripts/setup.sh 和 scripts/notify_scarf.sh
• 演示登录：脚本会打印一个 Control Center 的演示邮箱和密码，密码请直接看脚本的输出
• 测试数据：Exploration Guide 称托管沙盒是测试环境
• 文档链接：README 链接的一些文档页在 2026 年 11 月 3 日返回了服务器错误或没有响应，所以工具包用的是能打开的那些页面
• 更新：README 没有给 Docker 途径的更新步骤，版本信息请看 CHANGELOG.md
• 旧的 SDK：README 说 hyperswitch-sdk-react-native 正在弃用，已经从 npm 移除，请改用 react-native-hyperswitch
• 没覆盖的部分：工具包没有给移动端 SDK、hyperswitch-suite、hyperswitch-prism 和 decision-engine 的安装步骤，因为它们的 README 没有读
• 许可证：Apache-2.0。LICENSE 文件是标准的 Apache License 2.0 文本。文件末尾方括号里的“Copyright [yyyy] [name of copyright owner]”是附录里套用该许可证的样板文字，文件没有写出任何版权持有人