微信服务号支付接入指南

服务号本身不提供收银台，它的作用是把用户带到微信内的H5页面或关联的小程序，并在支付完成后负责通知。服务号场景下最常用的支付方式是JSAPI支付（公众号支付），前置条件是先通过网页授权拿到用户的openid。本文按「场景—接入步骤—与小程序的差异—排查—安全—对账」的顺序梳理，可直接作为技术联调的检查清单。

一、服务号支付场景

典型链路有三条：菜单入口，用户点击自定义菜单进入微信内H5商城下单支付；消息回跳，用户点击模板消息或客服消息中的链接，回到待付款订单继续支付；线下扫码，门店物料二维码指向带门店参数的H5页面完成支付。这三条链路的共同点是页面都在微信内打开，因此都可以使用JSAPI支付。如果用户在微信外的浏览器打开同一个页面，JSAPI是无法调起的，需要改用H5支付（即微信外网页支付）或引导回微信内，这一点在做营销短信落地页时最容易踩坑。

二、接入步骤

1. 完成微信认证并申请商户号：服务号需处于已认证状态，微信支付商户号的主体必须与服务号主体完全一致，否则无法绑定。
2. 在商户平台绑定AppID并配置JSAPI支付授权目录：授权目录要填到发起支付的页面所在目录（注意区分目录与具体页面），协议、域名、路径必须与线上实际地址一致。
3. 在公众平台配置网页授权回调域名：域名须已完成ICP备案，且与H5实际访问域名一致；同时在服务器根目录放置平台要求的校验文件。
4. 实现网页授权取得openid：一般用snsapi_base静默授权，拿到code后在服务端换取openid，不要把AppSecret放到前端。
5. 服务端统一下单：以JSAPI交易类型下单，传入商户订单号、金额（单位为分）、商品描述与openid，拿到预支付交易会话标识。
6. 前端调起支付：用服务端下发的参数调起微信支付控件，前端回调只能用于界面提示，不能作为支付成功的依据。
7. 处理支付结果异步通知：对通知做验签、金额校验与幂等处理，确认成功后更新订单状态，并按平台要求返回成功应答；同时保留主动查单作为兜底。
8. 发送服务通知：订单状态更新后再触发支付成功、发货等模板消息，文案必须与订单实际状态一致。

三、与小程序支付的差异

小程序侧不需要网页授权，openid通过登录凭证在服务端换取；服务号H5则必须先走OAuth，多一次跳转，弱网下的流失也更明显。此外H5页面的首屏性能直接影响支付转化，需要做资源压缩、接口合并与骨架屏。因此高复购的零售类客户通常采用组合方案：首单和主要交易放在小程序，由服务号负责发券、发货、售后进度等通知，把用户引回小程序复购；只有在需要灵活活动页、跨端投放或不适合上小程序的场景，才让H5承担成交。需要注意的是，同一用户在服务号与小程序下的openid不同，会员系统必须以unionid为主键，否则跨端订单会对不上人。

四、常见问题排查

联调阶段最高频的四类问题及排查方向：调起支付时提示配置错误，通常是JSAPI支付授权目录与当前页面路径不匹配，或域名带了端口、协议写成http；提示openid不正确，多为下单时传入的openid来自另一个AppID，常见于测试环境与生产环境混用；签名校验失败，检查参数排序、空值是否参与签名、密钥是否与当前商户号对应、以及金额字段是否被前端改成了带小数的字符串；回调收不到或重复收到，前者检查回调地址是否公网可达且未被防火墙拦截，后者属于正常重试机制，必须用商户订单号做幂等。建议在开发期就把每次下单与回调的完整报文落日志，出问题时可直接比对。

五、安全要求

四条必须落实：凭证集中管理，access_token与AppSecret、商户API密钥、证书只保存在服务端并集中缓存，token需处理并发刷新，避免多实例互相顶掉；回调必须验签，同时校验订单号存在、金额与本地记录一致、订单未被处理过；身份映射防串号，openid与会员ID建立唯一映射，下单时以服务端会话中的身份为准，不接受前端传入的用户标识；金额只信服务端，商品价格、优惠、运费全部在服务端重新计算，前端传来的金额一律丢弃。此外，所有页面强制HTTPS，日志中不得明文记录密钥与完整手机号。

六、退款与对账

退款需在服务端调用退款接口并处理异步结果，退款单号同样要做幂等；部分退款要注意累计退款金额不得超过订单实付金额。对账建议每日执行：下载商户平台的交易账单与资金账单，与本地订单表逐笔核对，重点关注三类差异——本地已支付但账单无记录（多为回调伪造或测试数据）、账单有记录但本地未支付（回调丢失，需要主动查单补单）、金额不一致（优惠计算错误）。差异必须当日闭环，并保留处理记录，这既是财务要求，也是应对用户投诉时的依据。退款到账时间以微信支付的实际规则为准，客服话术里不要承诺具体到小时。

七、上线前自查清单

• 服务号处于已认证状态，商户号与服务号主体一致，AppID已绑定。
• 网页授权回调域名、JSAPI支付授权目录、页面实际访问地址三者一致，且域名已备案。
• 用真实微信号完成一笔小额真实支付，验证下单、调起、回调、通知、订单状态五个环节。
• 验证一笔退款全流程，并确认退款通知与客服话术一致。
• 模拟回调重复推送与延迟推送，确认幂等逻辑生效。
• 在微信外浏览器打开支付页面，确认有明确的引导提示而不是白屏或报错。
• 证书与密钥的到期日已登记到运维日历，并指定责任人。

八、写在最后

支付环节的事故成本最高，值得在上线前多花一轮时间做真实链路验证。把上面第七节的清单打印出来逐项勾选，通常可以避开绝大多数上线首日的支付问题。若需要一份包含下单、回调、退款、对账四组接口的联调用例模板，可通过右下角客服微信联系看店通顾问索取。