Skip to main content
沙盒跑通不等于可以上线。这一页列出切生产前要过的东西。

先完成开户认证

生产环境要真正收款和提现,得先通过开户认证。 系统设置里提交开户资料,用于审核你的收款主体和结算资质。状态有未开始、审核中、审核未通过、已通过四种。 对走上线引导的商户,企业认证(KYB)或个人认证(KYC)通过后,系统设置里的其余功能就会解锁,不需要等创建产品或完成首笔支付。
部分生产账户的后台只显示「完成开户认证」一步,没有后面两步。那种情况下这一步用于开通提现资格。
认证和技术接入可以并行——生产资料在审的时候,你照样能在沙盒写代码调试。沙盒有自己的开户认证步骤,是自动通过的,不受生产审核状态影响。

分四层验证

按这个顺序验,前一层没过就别急着做下一层。
1

本地逻辑

不接真实支付,先验金额计算、商品快照、幂等键、状态流转和发货去重。这一层用单元测试就能覆盖。
2

模拟 Webhook

自己构造带签名的请求打给你的 Webhook 接口,验证:原始请求体读取正确、HMAC 算得对、重复事件不会重复发货、乱序事件不会覆盖新状态、错误签名会被拒。
3

真实沙盒 Session

由后端创建真实的沙盒 Checkout Session,验证前端能正常跳转或挂载。
4

真实沙盒付款

用测试卡完整走一遍。确认本地订单变成 paid,而且发货、充值或开通权益也真的执行了。
第四层的验收标准是”业务真的完成了”,不是”Webhook 返回了 200”。检查你自己数据库里的发货状态,不要只看日志。

场景清单

做了订阅还要验这些

做了优惠还要验这些

目前公开提供的沙盒测试数据只有成功卡 4242 4242 4242 4242,没有可公开的 failed、3DS、pending 测试数据。所以上表里这三行暂时没法在沙盒里跑出来,要靠代码审查和单元测试覆盖。pending 尤其要认真看一遍——确认你的代码不会把它当成失败然后重新发起扣款,那是造成重复扣款最常见的原因。

切生产要改什么

上面这些都是环境相关的配置。账号本身不用换 —— 沙盒和生产用同一套登录账号密码,从沙盒后台右上角的「进入生产环境」切过去就行,不需要重新注册。
生产密钥要在生产后台重新初始化,Webhook 端点也要在生产环境重新注册,签名密钥跟沙盒不是同一个。忘了换的话,生产事件会全部验签失败——而且失败得很安静,你的服务照常返回 401,客户付了钱但永远不发货。
上线后建议先用一笔小额真实交易走完全流程,确认收款、Webhook、发货、对账都正常,再放开流量。

出问题怎么查

客户说付了钱,但订单没变

按这个顺序查:
  1. 后台 交易 页面能不能找到这笔交易,状态是什么(注意去对应环境的后台找,沙盒和生产的交易是分开的)
  2. 找不到就用 sessionIdGET /checkout/session/{id},看 statusorderId
  3. orderId 就查 GET /order/{id},看 Order 的 status 是不是 success
  4. Order 是 success 但你的订单没更新,说明问题在 Webhook 那一段,往下看

收不到 Webhook

验签一直失败

最常见的三个原因:
  • 用了解析过的 body 而不是原始请求体(Express 里用了 express.json()
  • 签名密钥没换成当前端点的(轮换过,或者从沙盒复制过来的)
  • 拼接时少了中间那个 .,或者时间戳用了自己生成的而不是请求头里的

客户被扣了两次

检查这几处:
  • 下单接口有没有防重复提交,同一个购物车重复点会不会建出两条订单
  • pending 状态有没有被当成失败,然后自动重新发起了扣款
  • Webhook 有没有按 event.id 去重
merchantReferenceId 不是幂等键。用同一个值创建两次 Session,Clink 会给你两个不同的 Session,两笔都能付款。

开户认证没通过

系统设置里看审核未通过的具体原因,按提示补充或更正资料后重新提交。技术接入不受影响,可以继续在沙盒调试。

上线之后

余额与结算

钱什么时候能提,费用怎么算。

退款

退款流程和状态同步。