发卡平台对接详细流程:从商品配置到支付回调与自动发货验收
准备了商品、域名和一套发卡程序,下一步怎样让客户付款后可靠收到自己的授权码?本文按一次完整接入的顺序梳理准备、开发、联调和上线。示例面向自有或已获授权的数字商品;文中的字段名与伪代码仅用于说明映射关系,不是稳付pay的实际接口文档。
文章目录
第一步:明确商品、支付和交付各自负责什么
先画出三条边界:发卡平台管理商品、订单和交付;支付服务识别交易并通知;结算流程按约定将应结款项交付给商户。付款成功、商品已交付、结算已到账是三个事实,不能共用一个“完成”开关。
- 准备商品确定 SKU、库存与售后规则
- 创建支付后端固定订单金额与支付尝试
- 验证付款可信回调配合服务端查单
- 自动交付事务分配与持久任务重试
例如售卖自己开发的软件激活码,订单可以已付款、待发货,同时尚未进入当次结算。客户已经付款却因结算队列未完成而一直拿不到商品,通常说明系统把这几条链路错误绑定了。
第二步:备齐商品、库存与运行环境
给每个规格分配稳定的商品编号,明确授权期限、适用版本、购买数量上限、交付形式与售后联系方式。平台展示价格和服务端结算价格使用同一可信数据源;不要让浏览器自行决定应付金额。
库存先区分可售、预留、已分配、已交付。预留应有有效期和原子释放条件;支付等待时间与预留时间需要协调。已经确认付款的订单不能因为一个到期任务执行,就被改回未付款并无条件释放库存。
上线环境至少准备有效 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),达到配置确认条件后提供秒级业务回调,不代表区块确认仅需几秒。商户后台仍在开发,请先联系确认协议、结算条件和联调范围,再编写对应适配层。
参考资料与技术文档
官方资料用于核对通用技术原理。示例需结合实际接口文档与运行环境验证。