用 REST API 接入加密货币收款：生产可用指南

加密货币支付 REST API 让商户后端创建账单、把买家引向付款体验，并在链上确认后履约。生产级集成不依赖一段示例报文，它建立在四个稳定的契约上：认证请求、稳定的外部订单标识、验证过的 webhook，以及一个在重复投递下仍然正确的本地订单流转。

Paymos 在沙盒和正式环境提供同一套 Merchant API、凭证分开。API 可创建、查询和取消账单与转出，读取余额，在沙盒模拟受支持的结果，以及创建公开的 Low-Code SDK 账单。

Merchant API 能管什么？

收款侧覆盖账单的创建、查询和取消。商户后端把自己的订单号接到 Paymos 账单上，然后选择面向客户的界面：托管收银台、内嵌 iframe、Low-Code SDK，或其他围绕商户订单流程自建的界面。

转出侧创建、查询和取消转出，余额操作暴露可用资产余额。这些能力使用与收款分开的凭证。沙盒还能模拟受支持的支付和转出结果。每项能力都应挂在服务所需的最小凭证范围下，不要在收银、财务和浏览器代码之间共用一把密钥。

API 请求该怎么认证？

Paymos Merchant API 用 HMAC-SHA256 认证，不是 Bearer token。HMAC 把请求绑定到共享密钥上，又不把密钥本身当凭证发出去——但集成方仍要在存储和部署环节保护密钥。

只在受信任的服务端签名。Merchant API 密钥不能出现在 JavaScript、移动安装包、公开仓库或分析日志里。收款和转出凭证分开，只创建账单的收银服务就不该持有转出凭证。通过受控的部署流程轮换凭证，防止旧部署继续用已退役的密钥。

环境和凭证怎么隔离？

沙盒和正式环境使用分开的凭证、相同的 API 面。这让沙盒可以验证集成行为而不动用真实链上资产，但两个环境不能互换。

不同环境的密钥用不同名字存储，基础配置分开，运行日志里带上环境标识。沙盒服务绝不应拿到正式凭证。切到真实收款时改环境配置，而不是改业务逻辑。webhook 密钥同理：接收方在改动订单之前，必须知道事件来自哪个环境。

账单创建怎么安全地跨重试？

在商户订单系统里生成 external_order_id，并在该订单生命周期内保持稳定。Paymos 用这个调用方提供的值创建账单：重复使用同一外部订单号返回已有账单，该操作没有单独的 Idempotency-Key 头。

持久化订单与其 Paymos 账单的关联。连接在收到响应前断开，就用同一个 external_order_id 重试。不要因为 HTTP 尝试变了就生成新值——标识代表的是业务订单，不是网络请求。

账单创建之后接哪个收银界面？

托管收银台提供自适应页面、二维码支付和受支持的钱包深链，可跳转使用，也可嵌进 iframe。Low-Code SDK 支持固定金额、JavaScript 金额回调、DOM 金额来源和自定义按钮流程，含 iframe 和跳转两种模式。

收款链接适合直接发给买家的账单。官方 CMS 插件覆盖 WooCommerce、WHMCS、OpenCart、PrestaShop、Magento 2、Shopware 6、CS-Cart 和 Easy Digital Downloads。当商户后端必须自己掌控订单创建、状态流转和履约，同时仍用 Paymos 受支持的收银体验时，Host-to-Host 是对的界面。

webhook 签名怎么验？

每个 Paymos webhook 带 X-Webhook-Signature 头，格式为 t={timestamp},v1={hmac_hex}。用配置的 webhook 密钥重算 HMAC-SHA256，再用定时安全的相等比较校验。必须先完成认证，事件才能改动账单、订单、库存或权限。

webhook 密钥轮换有过渡期：当前密钥和上一把密钥的签名都可被接受。接收端要按这个过渡配置，过渡期结束后移除旧密钥。不要用 IP 白名单替代验签——网络来源和消息真实性解决的是两个不同问题。

投递失败时接收端怎么办？

一个 webhook 投递周期共 11 次尝试，重试间隔从 1 分钟递增到 8 小时，完整周期约 16 小时。接收系统恢复后，失败或无法送达的事件可手动重放。

本地订单更新要做到同一笔付款不会触发两次履约。在开放权限、发货或入账之前，先持久化一条业务引用。重复通知到达时查到已有结果即停止。手动重放必须走和自动投递相同的路径，运维才不会意外绕过防重复规则。

沙盒测试怎么组织？

沙盒通过与正式环境相同的 API 面模拟受支持的支付和转出结果。用它测成功支付、失败支付、转出结果、验签、重复创建账单、投递恢复和对账，全程不动真实资产。

测试数据绑定稳定的 external_order_id，重复测试描述的才是同一笔业务订单。演练手动重放 webhook，确认履约仍只发生一次。切换环境前，核实服务只从正式密钥库读取正式凭证，且不再配置任何测试回调地址。

商户什么时候履约订单？

付款满足适用的确认策略、且 webhook 验签通过之后再履约。Paymos 的确认要求取决于网络和支付金额：小额付款所需确认更少，大额付款要求更强的终局阈值。固定结算时长因此不属于集成契约，底层风险模型见确认指南。

履约前先套项目的少付容差。新项目开出来是 0.1%，可调范围 0% 到 2%，0% 就是严格匹配。容差内的付款按实收金额完成，差额没人补。低于阈值时，单次付款账单变为少付，多次付款账单可保持打开。

生产加固要做什么？

收款、转出、沙盒、正式四套凭证分开。每个 webhook 都用 HMAC-SHA256 加定时安全比较验签，为新旧密钥轮换过渡期做好准备，履约做到防重复。监控 11 次尝试的投递周期，把手动重放流程写成文档。

webhook 目标地址必须是公网地址。Paymos 屏蔽回环、私网、链路本地、CGNAT 和 IPv6 ULA 地址，也不跟随自动 HTTP 重定向。最后，把 Paymos 账单状态与商户订单系统对账。当超时、重复创建、延迟投递、手动重放或少付都产生不出错误订单结果时，这个集成才算就绪。