电子商务支付的区块链 API:订单地址、Webhook 与确认数
网店如何通过区块链 API 收取和支付加密货币:每笔订单一个地址、Webhook、链上确认数、退款以及测试网检查。文中还说明订单记录应保存哪些字段、价格变动和部分付款的处理方式、退款与手续费的规划,以及上线前的测试清单。
审核: Maurice Sobiera
电子商务场景下的区块链 API 是一种 REST 接口,让线上商店无需运行自己的区块链节点,即可创建付款地址、检测到账的加密货币付款,并发送退款或付款。商店通过 HTTPS 与 API 通信,并在付款到达时收到 Webhook。密钥和确认规则仍由商店自己掌控。
网店如何通过 API 接受加密货币付款?
为每笔订单分配一个专用的充值地址,用 Webhook 监听该地址,并在确认金额匹配时把订单标记为已付款。流程分为五步:
- 使用
POST /api/v2/{blockchain}/addresses为订单创建一个地址。 - 使用
POST /api/v2/{blockchain}/webhooks为该地址注册 Webhook,并把订单号填入reference字段。 - 向客户展示地址、金额和过期时间。
- Webhook 到达时,校验
X-Signature请求头,并在链上核对金额和代币。 - 达到您事先确定的确认数之后再发货。
每笔订单一个地址可以消除猜测:发送到该地址的任何付款都属于该订单。付款 Webhook 指南展示了接收端代码,Laravel 教程则在一个 PHP 框架中演示了相同的流程。
订单记录应保存什么?
保存足够的数据,使您能够自行判断某笔付款是否完成。Webhook 告诉您发生了某件事,您的订单记录则告诉您本应发生什么。
| 字段 | 用途 |
|---|---|
| 订单号 | 同时作为 Webhook 的 reference 发送,便于匹配事件 |
| 网络与代币 | 客户必须使用的链和合约 |
| 充值地址 | 为该订单创建的地址 |
| 应付金额 | 开具发票时由商店价格折算得出 |
| 发票过期时间 | 超过此时间,价格不再有效 |
| 所需确认数 | 您针对该网络和订单规模所定的规则 |
| 状态 | 待付款、部分付款、已付款、已过期或已退款 |
有了这些字段,Webhook 处理程序就只是一次简短的比对:按 reference 查找订单,检查网络和代币是否一致,把收到的金额累加到已收总额中,然后更新状态。以正确地址接收错误代币的付款属于正常情况,处理程序必须能够识别,因为一个地址可以接收其所在网络上的任何代币。
商店应等待多少个确认数?
这取决于网络和订单的价值。比特币开发者文档中关于付款处理的部分指出,零确认的交易在未经风险分析时不应被信任,处理高价值交易的软件应至少等待六个确认,大约需要一小时。在 TRON 上,当 27 名超级代表中至少 19 名在某个区块之上继续出块时,该区块即被固化;根据 TRON 共识文档,正常情况下这大约需要一分钟。
请按网络和订单规模分别确定规则,把它写下来,并在代码中执行。低价值的数字商品可以在一次确认后发货,高价值的实物商品则应等待更久。
价格变动怎么办?
以您自己的货币固定价格,在开具发票时进行折算,并让发票过期。比特币文档指出,汇率会波动,与法币挂钩的发票必须设置过期时间,而大多数支付系统会在 10 到 20 分钟后使发票失效。较短的时间窗口降低了汇率风险,但也提高了客户延迟付款的可能性。
请事先决定如何处理迟到或部分付款。大多数商店会将其退款,或要求客户向同一地址补足差额。
退款和付款如何进行?
通过您掌控的地址,以普通交易的方式发送。原生代币使用 POST /api/v2/{blockchain}/transactions,代币则使用代币端点,例如 transactions/erc20、transactions/bep20 或 transactions/trc20。退款需要客户的退回地址,而且必须单独询问,因为付款的发送方并不总是应收回资金的钱包,例如付款来自交易所时即是如此。
让订单地址的资金保持短暂停留。将收到的付款转入您离线持有的钱包,订单地址仅用于收款。我们的安全建议说明了如何保存密钥。
如何控制网络手续费?
请在发送端规划手续费。从订单地址转出代币,在 EVM 网络上需要 Gas,在 TRON 上则需要能量或带宽,而订单地址必须为此持有足够的原生代币。在 TRON 上,赞助或租用能量可以降低 TRC-20 转账的成本。我们关于 TronFuel 与已弃用的 Paymaster的文档介绍了当前的选项。TronFuel 是一项独立服务,有其自己的文档。
上线前如何测试集成?
使用测试网。在任何请求中添加请求头 X-Network: testnet,同样的调用即可在测试网上运行,无需真实资金。请测试一笔完整订单、少付、多付、迟到付款,以及一个未能到达您服务器的 Webhook。失败的 Webhook 不会自动重试,它们会出现在 GET /webhooks/notifications/failed 中,并可重新发送,因此商店应检查该列表。
是否需要核实客户身份?
这取决于您所在的辖区和您的业务模式,API 不会替您决定。Chaingateway 是非托管的。在决定哪些核查适用于您的商店之前,请阅读我们关于加密支付 KYC的文章。
准备好自己动手构建了吗? 获取你的 API key — 7 天试用,无需信用卡 — 或查看 区块链 API 获取完整的 endpoint 参考。