一笔 PolyPay 托管支付如何完成

按照实际代码流程说明 Hosted Checkout 提供方选择、Stripe Checkout、加密货币结算与签名 Webhook 投递。

最近一次对照 PolyPay 实现审核：2026 年 8 月 31 日。

Stripe 授权与 Stripe Checkout 除配置的灰度规则外，还要求商户具备有效付费或按量套餐。只有套餐、商户连接与收付款能力均就绪后，Hosted Checkout 才会展示 Stripe。

支付生命周期概览

1. 商户使用商户订单号、金额、资产、网络和可选回调地址创建订单。
2. Hosted Checkout 只展示当前订单真正可用的 Stripe、Crypto 或两者。
3. 商户先通过 OAuth 授权已有的 Stripe Standard 账户。选择 Stripe 时，PolyPay 创建服务端 Payment Attempt，并在该商户账户作用域创建 Direct Charge Checkout Session；Charge、余额、退款和争议均留在商户 Stripe 中。选择 Crypto 时分配已启用的收款钱包和精确应付金额，并记录独立的 Payment Attempt。
4. Stripe 由签名 Provider Webhook、Connected Account 主动回查和陈旧尝试定时补偿共同确认；Crypto 由链监听器独立确认。
5. 只有第一个完成验证的 Provider 能把订单推进为已支付并触发一次履约。随后确认的 Stripe 或 Crypto 支付会进入去重的人工处置队列，不会再次履约；商户只收到一次已支付 Webhook。

1. 创建订单与幂等

商户传入的 mch_order_id 在商户和部署自动选择的支付隔离范围内唯一。商户创建订单时不需要选择或提交环境，Hosted Checkout 会自动使用当前部署已连接的 Stripe 账户。重复请求一个仍有效的订单时，系统返回已有订单，而不是静默创建另一个待付款订单。订单过期后，Hosted Checkout 可以复用同一商户订单号，并在重新选择支付方式后创建新的支付尝试。响应包含 trade_id、actual_amount、address、expiration_time 和 payment_url。

在 Hosted Checkout 选择 Stripe 或 Crypto

Stripe 与 Crypto 同时可用时，付款人先选择一级 Provider，再继续选择加密资产和网络；只有 Crypto 可用时，Hosted Checkout 会跳过 Provider 层，直接进入资产与网络选择。只有当商户具备有效付费或按量套餐、连接状态可用、收款与结算能力就绪、商户开关已开启，并且订单满足币种、金额和灰度规则时，Stripe 才会出现。套餐过期后，已保存的 Stripe 连接和开关会保留但冻结：Hosted Checkout 隐藏 Stripe，创建新 Stripe 尝试也会被拒绝；恢复有效套餐后自动恢复。选择 Stripe 后，订单从“等待选择支付方式”进入“等待支付”，并创建 pending Payment Attempt；从 Stripe 返回时，服务端会失效未支付 Session、取消该尝试并恢复支付方式选择。如果 Stripe 等待支付期间重新打开原支付链接，Hosted Checkout 会展示 Provider 选择，而不是展示字段为空的加密货币支付页；再次选择 Stripe 时会安全复用当前有效的 Stripe attempt。Stripe Checkout 使用服务端保存的订单金额，浏览器不能覆盖。Stripe 回跳页只轮询服务端 Payment Attempt，不会根据 URL 参数把订单标记为已支付。

Hosted Checkout 使用 GET /api/v2/checkout/orders/{trade_id}/payment-providers 查询一级 Provider；使用 POST /api/v2/checkout/orders/{trade_id}/payment-attempts 并传 provider=stripe 创建 Stripe 尝试；使用 GET /api/v2/checkout/payment-attempts/{attempt_id} 轮询状态。具备有效付费或按量套餐的商户可在 /api/v1/pay/merchant/payment-providers/stripe 下授权已有 Standard 账户、提交一次性 OAuth 回调、刷新状态、启停和撤权。冻结期间仍可读取 status，但免费或过期套餐调用管理接口会被拒绝。PolyPay 只保存 acct_ 标识，不保存商家的 Stripe Secret Key 或 OAuth Token；平台将日常支付使用的 Restricted Key 与仅用于 OAuth 换码和撤权的完整 Secret API Key 分开保存。connect、enable、disconnect 必须携带已认证的 step-up ticket。

2. 分配 Crypto 收款钱包与精确金额

PolyPay 从支持目标资产和网络的商户已启用钱包中选择地址，并在订单有效期内锁定“钱包 + 金额”组合。因此付款方必须发送 actual_amount，接入方不应自行重新计算或取整。

选择支付方式时的参考网络手续费

未预设币种和网络时，只要商户支持 USDT，Hosted Checkout 就默认选中 USDT。默认收款钱包支持 USDT 时，选中并置顶该钱包网络；否则优先选择 TRON，再使用其他首个支持 USDT 的网络。选择 USDC 时，Ethereum 紧接默认钱包网络之后。默认网络与常用网络相同时只出现一次。商户不支持 USDT 时，才使用默认钱包的优先币种。币种卡片始终使用产品固定顺序，不因默认钱包改变排列。付款方每次切换币种时，Hosted Checkout 都自动选中该币种排序后的第一个网络，付款方仍可改选其他兼容网络。支付方式响应会按资产和网络返回短时有效的 fee_quotes。PolyPay 从链 RPC 或费率接口同步实时单位费率，结合标准转账资源模型计算参考值，并按手续费币种的实时 USD 行情返回 standard_fee_usd。Base 与 Optimism 还会加入 OP Stack GasPriceOracle 返回的代表性 L1 数据费和 Operator Fee。available 表示当前有效，stale 表示本次刷新失败后保留的最近成功观测，unavailable 表示不应展示数值。Hosted Checkout 为保持选择界面简洁，不展示手续费估算；最终网络手续费以钱包显示为准。

无需登录即可调用 GET /api/v1/pay/public/network-fees，查询全部支持转账类型的较低、标准和快速手续费；PolyPay Tools 使用同一数据，横向对比 USDT、USDC 与各网络本位币的标准速度估值。 打开实时手续费查询工具.

公开 GET /api/v1/pay/public/platform-stats 接口为官网提供脱敏的当前监听状态，只返回统一支付网络与资产数量、各监听器当前已完成的最高区块、落后区块数，以及正常、降级、中断或未知状态；不返回钱包地址、交易 Hash、RPC 详情或内部错误。监控停用、数据不完整或快照过期时，官网显示状态暂不可用，不使用示例数据替代。

收款钱包地址审查

PolyPay 会在后台静默审查新添加的钱包，以及修改了地址或网络的钱包；钱包管理页面不会展示中间审查状态。地址确认属于交易所或托管平台后，钱包会被禁用，且不能编辑或重新启用。钱包管理页面通过禁用原因链接提供申诉和客服入口；只修改名称、币种和监听金额范围不会重新触发审查。

3. 使用 WalletConnect 或页面地址付款

对于 TRON 与 EVM 网络上受支持的 USDT、USDC 订单，托管收银台可以通过 WalletConnect 调起兼容钱包，要求钱包发送精确的代币转账。普通收款二维码在桌面端保持展示；移动端默认收起，通过“使用另一台设备扫码”按需展开，让精确金额和收款地址保持在主要位置。TRON 账户的 Active Permission 需要多份签名时，收银台先收集 TronLink 第一签并创建短时跨设备会话，再展示二维码供授权共同签名人确认；该多签二维码仍是移动端流程的必需步骤。手机对完全相同的交易追加签名，通过 getSignWeight 确认累计权重达到阈值后才广播。浏览器可以展示钱包返回的交易 Hash，但不会把 Hash 作为付款证据提交给 PolyPay。PolyPay 由链监听器独立发现转账，匹配订单锁定的网络、代币合约、收款地址和整数最小单位金额，并在达到所需确认数后才更新订单状态。二维码与手动复制地址也使用同一条服务端扫链确认路径。

4. 可观察的订单状态

5. Webhook 投递与验签

Stripe 事件进入 PolyPay 后，系统先使用对应环境的 destination secret 验证 Stripe-Signature，幂等保存 Provider Event，校验 Connected Account 作用域，并主动回查 Checkout Session 或 Charge 后才推进状态。随后 PolyPay 使用 Ed25519 v2 为商户回调签名。接入方应根据 Key ID 从平台 JWKS 选择公钥，验证签名覆盖的商户 ID、环境、时间戳、nonce 和原始请求体。非 2xx 响应会被视为投递失败。接入方应保存 event ID，并对每个事件做幂等处理。

6. 选择正确的事实来源

浏览器跳转只用于改善客户体验，不是付款证明；Stripe Checkout 和 Crypto 钱包跳转都遵循这一规则。商户应通过验签后的 PolyPay Webhook 或鉴权订单状态查询更新业务订单。Provider 与商户 Webhook 都可能重复投递，因此履约逻辑必须幂等。

责任边界

商户

持有收款钱包与已连接的 Stripe 账户、保护 API 凭据、在 Stripe Dashboard 处理退款和争议、验证 PolyPay Webhook，并幂等履行业务订单。

PolyPay

创建和跟踪支付订单、在商家账户作用域创建 Direct Charge Checkout、验证 Provider 事件、分配 Crypto 付款信息、监听已配置链，并发送签名状态事件；PolyPay 不接收商家的 Stripe 资金，也不收取 Application Fee。

付款方

在订单过期前使用页面显示的正确网络、地址、资产和精确金额。

具体接入请继续阅读 API Key 指南和 Webhook 安全指南。 API Key · Webhook Security

FAQ