先完成开户认证
生产环境要真正收款和提现,得先通过开户认证。 在系统设置里提交开户资料,用于审核你的收款主体和结算资质。状态有未开始、审核中、审核未通过、已通过四种。 对走上线引导的商户,企业认证(KYB)或个人认证(KYC)通过后,系统设置里的其余功能就会解锁,不需要等创建产品或完成首笔支付。部分生产账户的后台只显示「完成开户认证」一步,没有后面两步。那种情况下这一步用于开通提现资格。
分四层验证
按这个顺序验,前一层没过就别急着做下一层。1
本地逻辑
不接真实支付,先验金额计算、商品快照、幂等键、状态流转和发货去重。这一层用单元测试就能覆盖。
2
模拟 Webhook
自己构造带签名的请求打给你的 Webhook 接口,验证:原始请求体读取正确、HMAC 算得对、重复事件不会重复发货、乱序事件不会覆盖新状态、错误签名会被拒。
3
真实沙盒 Session
由后端创建真实的沙盒 Checkout Session,验证前端能正常跳转或挂载。
4
真实沙盒付款
用测试卡完整走一遍。确认本地订单变成 paid,而且发货、充值或开通权益也真的执行了。
场景清单
做了订阅还要验这些
做了优惠还要验这些
目前公开提供的沙盒测试数据只有成功卡
4242 4242 4242 4242,没有可公开的 failed、3DS、pending 测试数据。所以上表里这三行暂时没法在沙盒里跑出来,要靠代码审查和单元测试覆盖。pending 尤其要认真看一遍——确认你的代码不会把它当成失败然后重新发起扣款,那是造成重复扣款最常见的原因。切生产要改什么
上面这些都是环境相关的配置。账号本身不用换 —— 沙盒和生产用同一套登录账号密码,从沙盒后台右上角的「进入生产环境」切过去就行,不需要重新注册。
上线后建议先用一笔小额真实交易走完全流程,确认收款、Webhook、发货、对账都正常,再放开流量。
出问题怎么查
客户说付了钱,但订单没变
按这个顺序查:- 后台 交易 页面能不能找到这笔交易,状态是什么(注意去对应环境的后台找,沙盒和生产的交易是分开的)
- 找不到就用
sessionId查GET /checkout/session/{id},看status和orderId - 有
orderId就查GET /order/{id},看 Order 的status是不是success - Order 是
success但你的订单没更新,说明问题在 Webhook 那一段,往下看
收不到 Webhook
验签一直失败
最常见的三个原因:- 用了解析过的 body 而不是原始请求体(Express 里用了
express.json()) - 签名密钥没换成当前端点的(轮换过,或者从沙盒复制过来的)
- 拼接时少了中间那个
.,或者时间戳用了自己生成的而不是请求头里的
客户被扣了两次
检查这几处:- 下单接口有没有防重复提交,同一个购物车重复点会不会建出两条订单
pending状态有没有被当成失败,然后自动重新发起了扣款- Webhook 有没有按
event.id去重
merchantReferenceId 不是幂等键。用同一个值创建两次 Session,Clink 会给你两个不同的 Session,两笔都能付款。
开户认证没通过
在系统设置里看审核未通过的具体原因,按提示补充或更正资料后重新提交。技术接入不受影响,可以继续在沙盒调试。上线之后
余额与结算
钱什么时候能提,费用怎么算。
退款
退款流程和状态同步。