发卡平台支付对接:验签、幂等、库存锁与自动交付
自动发卡不是收到一个“支付成功”字符串就发出一份卡密。可靠的流程需要把可信支付通知、订单状态、库存分配和交付任务衔接起来,并允许网络重试、进程重启和人工修复。本文给出与供应商无关的通用设计;所有字段、签名方式和应答内容都要按实际接入协议实现,不能直接当作稳付pay的接口说明。
文章目录
将付款与交付拆成两个状态维度
至少区分待支付、已支付、已退款等付款状态,以及待分配、已分配、已交付和交付异常等交付状态。否则客户付款后遇到库存不足,系统只能在“成功”与“失败”之间二选一,无法保留真实的中间事实。
- 创建订单服务端固定商品、金额、币种与有效期
- 确认付款验签、核对字段并持久化支付事实
- 分配库存事务中锁定订单与对应卡密
- 执行交付持久任务重试并保留交付结果
购买数量、价格和优惠由服务器计算,不能直接采用浏览器提交的最终金额。订单保存当时的价格快照,之后商品涨价也不应改变已经创建的付款要求。
先验签,再核对商户、金额和业务归属
回调处理在后端执行,依照支付文档验证签名、签名覆盖的数据、时间窗口和密钥。供应商若要求使用原始请求体,应在框架解析或重新序列化之前保留原始字节。Stripe 的 Webhook 指南可作为这种机制的一个具体例子,其字段和签名头不能直接套到其他服务。
签名通过只说明消息符合该密钥对应的协议,还要核对商户身份、订单归属、支付交易号、币种、实际金额及最终成功状态。金额用明确的最小单位整数或精确定点数比较,不能采用有精度误差的浮点近似相等。
USDT 还需要核对网络、收款地址与对应的资产标识,不能只看代币显示名称。前端 return 地址、支付截图和客户口述都不能替代这些检查。密钥必须留在服务端,不能放在网页脚本中。
去重需要数据库约束,不能只写“先查询”
失败场景一:两条通知同时到达,两个进程都查询到订单未交付,于是各发一份卡密。先查询再写入之间存在竞争,单机运行也可能发生。去重必须落到数据库的唯一约束和事务中,而不是只依赖内存标记。
至少分别考虑事件去重、支付交易去重和业务交付去重。相同付款可能产生不同事件编号,只有事件编号唯一仍可能重复认领付款;同一事件重复投递则不应再次推进状态。已处理的重复通知,可以在核实其持久记录后按协议确认。
以下依次是通知表、付款表、交付任务表和库存分配表中的通用约束示意,不是同一张表的完整建表脚本;字段非空、作用域和实际语法需一并设计。PostgreSQL 的约束文档解释了唯一约束的数据库保障。
UNIQUE (provider, provider_event_id)
UNIQUE (provider, provider_transaction_id)
UNIQUE (order_id, fulfillment_kind)
UNIQUE (card_id)用事务保护库存分配,避免最后一份库存超卖
处理成功付款时,在事务中锁定对应订单,再检查它是否已经分配库存。对待分配卡密采用行锁或带状态条件的原子更新,分配记录与订单状态一同提交。不能先把卡密发给客户,再回头尝试把数据库标成已售。
如果采用比较并更新,也就是 CAS 思路,更新条件应包含“仍可用”,并检查影响行数是否恰好为一;影响零行时要重新选库存或进入缺货流程。多件订单应有明确的整体分配规则,不能无意中只交付一部分。
PostgreSQL 的行锁说明展示了并发访问的协调方式。锁应持有尽可能短的时间,外部邮件或授权接口不放进长事务;发生死锁或可重试冲突时,按数据库语义重试完整事务,并保持操作幂等。
用 Outbox 衔接数据库与外部交付
事务可以保证订单和库存一起保存,却不能让数据库与邮件供应商天然同时成功。解决思路是在提交业务数据的同一事务中,写入一条持久的待交付任务,也就是 Outbox;独立任务进程随后发送通知并记录结果。
# Generic flow; adapt to the actual provider protocol.
event = verify_provider_request(raw_request)
with database_transaction():
persist_inbox_event_once(event)
record_verified_payment_once(event)
allocate_inventory_if_needed(event.order_id)
persist_outbox_job_once(event.order_id)
return protocol_ack_after_commit()
这是流程示意,省略了重复事件、校验失败和缺货分支。无可用库存时应提交“已付款待处理”及受控人工任务,不创建虚假的已交付记录。持久化失败不能先返回业务接收成功,应按协议让对方重试或进入明确的补偿查询。
接收成功不必等到邮件发出,但前提是通知和后续任务已经可靠落盘。只有内存队列没有持久化时,提前应答后重启就可能永久丢失交付工作。
缺货、晚到付款与重复执行分别处理
失败场景二:订单超时释放了库存,客户的付款通知晚到。系统若忽略关闭订单,会留下已付款未处理;若直接沿用旧库存分配,又可能把已经卖出的码发给第二个人。应记录付款事实,重新检查库存和订单规则,转补货、人工履约或退款流程。
任务进程可能在外部交付完成后、写回成功状态前崩溃。重试时仍使用同一个交付编号;如果外部系统支持幂等键或结果查询,应优先使用。若对方没有相关能力,必须设计核对和人工分支,不能宣称仅靠本地队列即可做到外部操作绝不重复。
已分配的同一张卡密可以通过受控渠道重新展示给原订单客户,但不应因此再消耗一份库存。重发邮件与重新发货是不同操作,管理后台需要分清权限和审计记录。
退款和对账保留完整历史,不删除付款记录
退款是独立业务事件,可能有申请中、成功、失败或部分退款等状态。不要通过删订单或直接改回未支付表达退款。需要记录原支付交易、退款关联号、金额和操作人,并与支付侧的最终结果核对。
数字商品是否已被查看或兑换,影响售后处理,但不意味着可以任意自动退款或重新入库。无法撤销的授权码不能在退款后直接放回可售库存;可撤销授权也要先确认撤销结果,再决定后续动作。
定期比较支付记录与本地已付款订单,筛出本地缺失、金额不符、已付款未交付和退款未完成的情况。链上监控通知也需要关联到唯一业务订单,不能仅凭同金额转账猜测归属。确认条件及特殊交易处理应在接入时约定。
上线前按故障清单验收,并明确接口边界
- 伪造通知、错误签名、错误商户和错误金额都不能触发交付。
- 相同事件重复发送、不同事件关联同一交易,均不会重复分配。
- 并发购买最后一份库存时,只有一份有效分配记录。
- 事务提交失败不应答成功,提交后进程重启仍能继续处理。
- 邮件超时、任务中断和外部接口结果不明,都有核对入口。
- 缺货、晚到付款、退款和人工补发都有可追溯状态。
稳付pay的商户后台仍在开发,监控与回调服务已经开放。目前 USDT 支持 Tron(TRC20)和 Ethereum(ERC20),资金直接进入商户自有地址;达到配置的链上确认条件后提供秒级业务通知,不代表区块确认本身只需几秒。
本文没有提供稳付pay的实际接口地址、签名头或密钥获取流程。准备对接时,请先联系确认实际协议,再据此实现请求验证、应答与补单规则,完成测试后上线。
参考资料与技术文档
以下官方资料用于核对协议及实现原理。文中代码与场景用于技术解释,具体环境和正式接入协议应分别验证。