链上收款

发卡平台对接USDT:自有地址、链上确认与可靠回调

链上看见转账,不等于订单已经可靠收款;收到一次回调,也不等于可以重复发卡。把钱包、交易证据、支付状态和库存交付分开,才能让商户自行掌握资金,同时让数字商品交付可追溯。

文章目录

一、先确定资金边界:地址归商户,监控服务不保管资产

这里的发卡平台指数字商品、授权码或兑换码的自动交付系统。接入USDT时,客户应直接付款到商户自己的收款地址。稳付pay负责监听和识别交易、核对到账状态,再向商户业务系统回调;资金不经过稳付pay,平台不代收、不托管。

商户自己保管钱包和签名权限。提供公开收款地址即可进行只读监控,不应向监控人员提交助记词、私钥、钱包文件或远程控制权限。“我帮你配置”也不是索取这些资料的理由。资金掌握在自己手上,还意味着地址备份、付款核查与退款审批由商户负责。

二、网络、代币与确认条件必须在下单时固定

稳付pay当前支持USDT的Tron(TRC20)与Ethereum(ERC20)网络。USDT是资产名称,TRC20与ERC20描述不同网络上的代币标准;同名资产不能混用订单和地址。收银台应清晰展示网络,并要求客户确认,而不是只显示“USDT付款”。

核对项Tron / TRC20Ethereum / ERC20
链上交易证据核验成功执行的目标合约转账事件核验成功回执中的目标合约Transfer日志
确认依据按约定检查已确认、固化的数据按约定的区块确认或safe/finalized策略
共同要求核对网络、目标合约、商户地址、金额与订单匹配结果

TRON交易文档区分打包与固化;Ethereum JSON-RPC文档也区分不同区块状态。确认策略应由接入双方约定,不能用一个固定秒数代替。稳付pay的秒级回调指达到约定确认条件后的通知速度,不承诺区块链本身秒级确认。

三、订单匹配不能只靠“金额相同”

两名客户可以同时购买同价商品,一笔交易也可能包含多个代币转账事件。订单至少应绑定内部订单号、网络标识(Ethereum如chainId)、目标代币合约、收款地址、整数金额和有效期;交易证据另记交易哈希、事件序号、区块号与区块哈希。不能拿客户填入的交易哈希直接当作到账证明。

可为订单预分配商户控制的独立地址,或在共享地址模式下设置明确的支付会话与冲突规则。即便使用差异金额,也必须结合网络、合约、地址、有效会话与交易归属判断;遇到多个候选订单,应进入人工核对,禁止“先匹配第一条”。

Ethereum单条日志通常用网络标识、交易哈希及logIndex定位;TRON则按接口提供的事件序号建立稳定映射。保留原始事件与区块哈希,发生重组时重新核验所属规范链。这只定位当前规范链上的事件,不把logIndex视为跨重组永久不变的标识;交易哈希本身也不应代替事件级唯一性。

四、金额使用最小单位,地址和合约分别验证

不要用浮点数比较付款金额。先从受信任的目标代币配置确认精度,再用整数最小单位入库。例如精度为6时,12.34对应12340000个最小单位;这是换算示例,不意味着任意名叫USDT的合约都可信。链、合约地址和精度应来自维护的允许清单,不能采用客户提交的同名代币。

地址输入要按对应网络校验格式,并在确认页面完整核对。也要区分转账金额与钱包支付的网络费用:客户付出的手续费不自动算入商品款。首次接入先做小额验证,核验实际收款地址和事件,避免把页面显示成功当成链上收款成功。

五、交易监听与发卡交付之间,保留明确状态

  1. 创建支付会话固定订单、网络、地址、金额与有效期
  2. 发现并核验转账检查成功执行的目标代币事件
  3. 等待约定确认保留区块信息并复核交易归属
  4. 持久化收款通知业务端验签、去重并更新订单
  5. 执行库存交付独立记录发卡结果与补偿任务
交易发现、确认、回调接收和商品交付是不同状态,不能合并成一个“成功”。

监听器应保存扫描游标,断线后补扫已遗漏区间,并允许小范围重叠扫描。重复扫描依靠唯一约束去重,而不是依赖“理论上不会重发”。未满足确认条件的转账保持待确认;节点数据落后或事件被撤销时暂停推进,不能继续发货。

例如在商户数据库中,为支付事件设置非空复合唯一键,为每笔订单建立唯一的交付记录。PostgreSQL约束文档说明复合唯一约束的作用;具体键应结合网络事件模型设计,不能机械套用到所有链。

六、可靠回调要解决来源、持久化和幂等

回调使用HTTPS,按接入双方确定的协议校验签名、时间戳和事件身份,并校验内部订单、币种、网络与金额。若签名覆盖原始请求体,就必须在解析、重排JSON之前保留原始字节。密钥轮换、时钟容差与重试规则都应在联调时明确,本文不虚构稳付pay接口地址或签名字段。

可以借鉴Stripe官方Webhook指南对重复事件和验签的处理原则,但它不是稳付pay的接口规范。验签成功后先把通知可靠写入数据库或持久队列,再尽快返回约定的成功响应;写入失败不能抢先确认。慢速发卡由后台任务处理。

同一回调重发十次,收款状态只能推进一次,交付也只能发生一次。把支付更新与待交付任务写入同一事务,交付任务再锁定订单和库存;失败后重试已有任务,不重新生成第二张卡。回调暂时失败时可重试并补查,客户浏览器跳转不能代替服务端核验。

七、两个故障案例:重复通知与确认前重组

案例一:已发卡,但回调请求超时后又来一次

第一次请求可能已经提交事务,只是响应在途中丢失。第二次先按事件身份去重,再读取订单交付状态,返回已处理结果;不要仅凭“这次请求是新的”再取一张库存。核对通知记录、订单事务和交付记录,才能区分重复请求与真正漏发。

案例二:看见转账就发卡,随后交易所属区块变化

未确认的交易可能受链上重组影响。监听器应检查区块归属,Geth订阅文档说明Ethereum日志还可能带有removed标记;发现变化后回退待确认观察状态,并重新扫描核验。若在确认条件满足前已经交付,应进入人工事件处理,保留证据,不能自动向用户钱包执行扣回操作。

八、过期付款、缺货与退款,分别制定规则

订单超时不意味着地址不能再收到款。过期后发现付款,记录为待核对收款,不自动挪给新订单;少付、多付、同一订单分多次付款也应按预先约定处理。库存预留过期而款项后来确认时,要么重新核对库存并交付,要么进入人工退款流程。

支付完成和交付成功分别记录:付款已确认但缺货时,保持收款事实,告知客户待处理,而不是把订单改回“未支付”。退款是商户钱包发起的一笔新链上交易,需要独立审批、核对退款网络和地址、记录手续费与交易哈希;不能凭付款来源地址自动退款,因为交易所代付地址可能并非客户可直接接收的地址。

九、上线检查:先让异常路径跑通,再扩大交易量

  • 确认收款钱包归商户控制,任何接入资料均不包含私钥或助记词。
  • 分别测试TRC20与ERC20的合约、精度、地址和确认策略。
  • 覆盖同价订单、重复事件、回调超时、断线补扫与确认前重组。
  • 演练过期付款、少付多付、缺货、发卡失败、对账和人工退款。
  • 确保日志能从订单追到支付事件和交付任务,同时遮蔽密钥与卡密。

稳付pay当前面向中小站长免费开放上述两条网络的监控与回调服务,企业级服务另行收费。商户后台仍在开发中,现阶段可联系配置接入。资金始终由商户自己的钱包掌握;具体确认策略、回调协议和异常处理方式,应在上线前完成联调确认。

参考资料与技术文档

以下官方资料用于核对协议及实现原理。文中代码与场景用于技术解释,具体环境和正式接入协议应分别验证。

  1. TRON官方:交易生命周期与固化
  2. TRON官方:TRC-20代币标准
  3. Ethereum官方:JSON-RPC、日志与区块状态
  4. Geth官方:订阅日志与重组的removed标记
  5. Stripe官方:Webhook验签、重复事件与响应处理
  6. PostgreSQL官方:唯一约束与复合键

继续完善你的站点

从网络、订单到资金通知,按业务场景确认每一步。支付接入与USDT监控需求,可通过联系页面沟通。

联系稳付pay ↗