接入实操

发卡平台对接详细流程:从商品配置到支付回调与自动发货验收

准备了商品、域名和一套发卡程序,下一步怎样让客户付款后可靠收到自己的授权码?本文按一次完整接入的顺序梳理准备、开发、联调和上线。示例面向自有或已获授权的数字商品;文中的字段名与伪代码仅用于说明映射关系,不是稳付pay的实际接口文档。

准备接入稳付pay:请查看代收开发文档,按真实字段完成MD5签名、下单、查单与回调处理。商户网关和密钥由技术人员单独提供;代付接口暂未开放。
文章目录

第一步:明确商品、支付和交付各自负责什么

先画出三条边界:发卡平台管理商品、订单和交付;支付服务识别交易并通知;结算流程按约定将应结款项交付给商户。付款成功、商品已交付、结算已到账是三个事实,不能共用一个“完成”开关。

  1. 准备商品确定 SKU、库存与售后规则
  2. 创建支付后端固定订单金额与支付尝试
  3. 验证付款可信回调配合服务端查单
  4. 自动交付事务分配与持久任务重试
交付依据可信的付款结果;商户结算进度另行记录与核对。

例如售卖自己开发的软件激活码,订单可以已付款、待发货,同时尚未进入当次结算。客户已经付款却因结算队列未完成而一直拿不到商品,通常说明系统把这几条链路错误绑定了。

第二步:备齐商品、库存与运行环境

给每个规格分配稳定的商品编号,明确授权期限、适用版本、购买数量上限、交付形式与售后联系方式。平台展示价格和服务端结算价格使用同一可信数据源;不要让浏览器自行决定应付金额。

库存先区分可售、预留、已分配、已交付。预留应有有效期和原子释放条件;支付等待时间与预留时间需要协调。已经确认付款的订单不能因为一个到期任务执行,就被改回未付款并无条件释放库存。

上线环境至少准备有效 HTTPS、独立测试配置、可靠数据库、持久任务进程和备份恢复方式。卡密只对所属订单授权用户展示,访问日志和错误堆栈不得记录完整卡密、私钥或支付密钥。

第三步:先确认接入能力,再做字段对照表

把实际协议逐项确认:身份认证、签名覆盖内容、原始报文要求、查询能力、支付状态、通知应答、重试方式、时区和金额精度。若平台现成插件不匹配,应修改适配层,不要用改页面模板代替支付对接。

本地业务信息对接时核对保存目的
商户订单号长度、字符和唯一范围贯穿商品、付款与交付
支付尝试号同一订单重试如何识别避免超时后重复创单
应付金额、币种单位、精度、允许状态阻止少付或币种错配
渠道交易号、事件号是否存在、作用域及查询方式付款认领与通知去重
回调地址、返回地址服务端通知与浏览器跳转区别分离业务确认和进度展示
网络、资产、收款地址USDT 对应网络和资产标识防止跨链或同名代币误认

表中的名称仅为业务概念;最终字段和签名方法以双方确认的真实文档为准,不能照抄本文当作请求格式。

第四步:后端创建订单,保存每次支付尝试

用户选好商品后,后端重新读取价格、核对库存和购买限制,生成商户订单号,保存金额快照、币种和有效期。调用支付服务前先保存支付尝试记录,使网络中断后仍能定位“这一次请求”。

创单请求超时只代表没有得到明确答复,不代表支付服务没有创建成功。优先按原商户订单号或约定查询条件核实;只有供应商协议支持幂等请求时,才以相同业务内容和约定的幂等标识安全重试。参考 Stripe 的幂等请求说明理解这种机制,不能假设所有渠道都支持同样的请求头。

客户重新选择支付方式时保留旧尝试的归属,避免旧通知被映射到新的渠道订单。若出现两笔真实付款,应分别记录并进入重复付款处理,不应发两份商品来掩盖问题。

第五步:展示支付指引,返回页面只展示进度

把服务端取得的支付链接或必要参数交给前端,展示订单号、应付金额、有效期和售后入口。对接 USDT 时还要展示准确网络与收款地址,不能只写“USDT”让客户猜网络。

客户支付后跳回网站、关闭网页、切换设备,都不应改变后端确认流程。返回页面只向自己的后端查询订单进度,不根据网址里的 success 参数直接交付。订单详情与卡密查询应验证登录身份或足够强的订单访问凭证。

OWASP 的第三方支付集成指南强调服务端验证与金额匹配。支付提示中的“已提交”“确认中”也要与“已支付”区分,避免把一笔尚未确认的转账误报成成功。

第六步:后端验签、查单并核对业务字段

接收通知时依实际协议验签,检查商户归属、订单、金额、币种及成功状态;需要原始请求体的协议,应在解析重写前保留原始字节。签名有效仍不能代替业务字段检查。

按接入方案使用已认证的服务端查单确认支付状态,尤其在回调缺失、创单超时或状态冲突时。查询暂时不可用就保留待确认并安排重试,不把网络错误当作“已失败”,也不凭付款截图自动发货。

Stripe 的 Webhook 文档说明了通知验证、重复投递和乱序等情况。通知接收成功必须符合协议,并以事件及后续处理责任已经可靠持久化为前提;先应答再只把任务留在内存,进程重启就可能丢单。

第七步:事务记录付款与库存,提交后异步发货

支付事实、库存分配和发货任务要能一起保存。对同一订单采用行锁或带状态条件的原子更新,事件、交易和交付分别设置适当范围的唯一约束。库存分配也应按订单行及购买数量设置唯一归属,重复处理返回原分配结果,不能因交付任务尚未完成就再取一张卡。只有“先查有没有,再写入”挡不住并发。

# Protocol mapping example, not a runnable payment integration.
event = verify_using_confirmed_protocol(raw_request)
payment = query_and_match_payment(event)
with database_transaction():
    lock_order(payment.order_id)
    persist_verified_event_once(event)
    record_payment_once(payment)
    if not fulfillment_exists(payment.order_id):
        if allocate_or_reuse_stock_once(payment.order_id):
            create_outbox_job_once(payment.order_id, "deliver")
        else:
            mark_paid_awaiting_stock(payment.order_id)
            create_outbox_job_once(payment.order_id, "stock_review")
return acknowledgement_required_by_protocol()

PostgreSQL 的事务说明可用于理解共同提交;行锁机制用于协调竞争。外部查询和邮件发送放在短事务之外;Outbox 是与业务数据共同落盘的任务记录,提交后由工作进程执行。示意省略异常捕获,生产实现仍需处理重复键、死锁和失败重试。

第八步:补齐缺货、晚到付款和退款分支

付款确认后发现无库存,保存“已付款待处理”,通知站长补货、协商交付或退款,不能退回“未支付”。过期订单收到有效的晚到付款,也先记录付款,再根据当前库存与约定规则处理,不能直接忽略。

发送邮件超时不等于邮件未发出。交付任务保持稳定编号;调用支持幂等的外部授权服务时复用对应标识,不支持时先查询或人工核对。重发原订单卡密与重新分配一张卡密是两种操作,前者不应再扣一次库存。

退款保留独立的申请、处理中、成功或失败状态,并关联原交易。已经展示或兑换的授权码不能简单恢复成可售;可撤销授权也要先核实撤销结果。退款或补发操作记录操作人、原因与关联单号。

第九步:用验收矩阵证明系统能应对异常

联调不只做一笔正常付款。为每条用例保存订单号、支付尝试号、验证结果、付款记录、库存分配和任务状态,让另一名维护者也能复核。

测试输入预期订单结果交付验收
真实成功付款已付款且交易可核对数量正确、仅交付一次
错误签名或金额不确认成功并记录原因不分配库存
相同通知并发到达同一付款只认领一次只有一份有效分配
创单超时、回调暂缺查单恢复明确状态不重复付款或漏发
最后一份库存被并发购买付款事实各自保存不超卖,缺货单可处理
付款晚到、页面已关闭保留已付款事实按规则补发或售后
提交后进程重启持久记录仍在任务恢复且不多发
退款与发货同时发生独立状态可追溯按协调规则处理冲突

供应商有测试环境时优先使用;没有时,事先确认小额实付、退款和费用规则。本文中的流程未替代实际渠道联调,也不能作为“已经通过验收”的证明。

第十步:小范围上线,回滚时继续处理旧订单

发布前保留可恢复备份、旧版适配程序及配置,确认变更后的数据结构能否回滚。先限制接入范围并关注待确认数量、验签失败、已付款未交付、任务积压与查单异常。

发现异常时可暂停新支付尝试,但应继续接收和核对旧订单通知,保留原协议兼容与密钥轮换安排。不能通过删除回调地址或清空队列“回滚”,否则旧付款可能永远没有归属。

稳付pay支持支付宝、微信等渠道接入,渠道代收后的 USDT 结算按双方约定执行;USDT 自有地址监控则由客户直接付到商户钱包。目前监控支持 Tron(TRC20)与 Ethereum(ERC20),达到配置确认条件后提供秒级业务回调,不代表区块确认仅需几秒。商户后台仍在开发,请先联系确认协议、结算条件和联调范围,再编写对应适配层。

参考资料与技术文档

官方资料用于核对通用技术原理。示例需结合实际接口文档与运行环境验证。

  1. OWASP:第三方支付安全集成
  2. Stripe:Webhook 验证、重试与重复事件
  3. Stripe:幂等请求
  4. PostgreSQL:事务
  5. PostgreSQL:行锁与并发
  6. PostgreSQL:唯一约束

按你的业务场景确认接入

说明商品、订单量、支付方式与结算需求,逐项确认接口、资金路径和异常处理。

联系稳付pay ↗