集成加密支付 API 不论服务商为何都遵循可预期的形状:你创建发票、转址或嵌入结帐页、随付款进展收到异步 Webhook、验证它们,并与自己的纪录对帐。困难之处不在顺利路径——而在边界情况。
内核流程
多数网关提供具相同生命周期的 REST API。你在服务器端调用它(绝不要在浏览器暴露 API 密钥),并把 Webhook——而非浏览器转址——当作订单是否付清的真相来源。
先设计你的订单状态机:待处理 → 少付/已付 → 已确认 → 完成,并为已过期与多付设明确分支。事先接好这些,能避免导致重复履约的纠结条件式。
- 以金额、币别、订单 ID 与 Webhook URL 创建发票。
- 显示托管结帐页,或自行渲染地址与金额。
- 为每次状态变更接收 Webhook 并验证其签章。
- 在履约前确认付款已达所需确认数。
- 把 Webhook 与链上交易及你的订单对帐。
创建发票
发票把一个特定金额绑到一个特定订单一段有限时间。把你的订单 ID 当作中继数据送出,让 Webhook 能无需猜测地对回,并保存网关回传的发票 ID。
报价会过期——网关会把汇率锁定数分钟。持久保存发票的到期时间与状态,让你的接口能显示倒数,也让迟到的付款被当作对帐案例处理,而非遗失的订单。
Webhook 是真相来源
付款后的浏览器转址是便利,而非保证——用户可能关掉分页。你的服务器收到的 Webhook 才是你要据以行动的。验证每一个 Webhook:在信任任何一个字段之前,先检查签章(通常是用你的密钥对原始内文做的 HMAC)。
让 Webhook 处理具幂等性。网关会重送,所以同一个「已付」事件可能到达两次;以事件或发票 ID 作为你处理的键,让重复送达成为无动作。快速回传 2xx 并把缓慢的工作异步处理,网关才不会逾时而无谓地重送。
确认与最终性
一笔付款可能在最终前很久就被看到(在记忆池中或零确认)。依金额与链订一个确认门槛,并只在达到后履约。对快速链上的小额稳定币付款这很快;对大额则多等一些。
以信任网关的「已确认」状态、而非你自己的首次目击来防范重组与双花,并且除非你接受风险,否则不要在零确认付款上放行商品。
对帐与失败情况
对帐是每日的工作,用来证明每笔「已付」订单都对应一笔真实的链上交易,反之亦然。在每笔订单上保存交易哈希、收到的金额与网络,让落差成为一次查找,而非一场调查。
为少付(买家送太少)、多付(退差额或折抵)、传错网络,以及过期后又付款的发票明确做规划。在规模上这些并非罕见的边界情况——它们是每周都有的事件,而能安静处理它们的系统,才是真正的「可上线」。
常见问题
我该信任浏览器转址还是 Webhook?
Webhook。转址可能在用户关掉分页时遗失,也可能被伪造。在服务器端验证 Webhook 的签章,并把它当作订单已付清的权威信号。
我如何避免同一个 Webhook 被处理两次?
让处理具幂等性。网关会重送,所以以发票或事件 ID 作为你逻辑的键,让重复成为无动作。绝不要因为同一个「已付」事件再次到达而把订单履约两次。
我该等几次确认?
取决于金额与链。快速网络上的小额稳定币付款几乎可立即视为最终;大额则值得等更多确认。使用网关的「已确认」状态,而非你自己的首次目击。
如果顾客少付或多付会怎样?
两者都要明确处理。网关会标示少付,让你可请求差额或退款;多付时你退还超额或予以折抵。事先把这些分支做好,正是示范与上线之间的差别。