微信支付对接这事儿，说简单也简单，说复杂能让人掉一把头发。它就像搭积木，官方给了图纸（文档）和积木块（接口），但你自己搭的时候，总会发现有些地方对不上，或者一碰就倒。这份攻略，就是帮你把那些最容易卡住、最容易出错的坑，用大白话提前标出来，让你在技术对接和维护的路上，走得更顺一些。
在写第一行代码之前，如果准备工作没做好，后面全是白费劲。
1. 账号和权限，别搞混了
这是最源头、也是最容易懵的地方。微信支付涉及好几个“号”，权限各不相同：
开放平台账号：如果你需要用户用微信账号快捷登录你的应用，或者把支付能力绑定到多个不同的小程序、公众号上，你需要它。它像个“集团总部”。
公众平台账号（公众号）：主要用于网页内支付、公众号内支付。用户关注你的公众号后才能支付。
小程序账号：用于小程序内支付。
商户平台账号：这是核心！ 不管钱最终从哪儿付（公众号、小程序、APP等），收款方都是这个“商户号”。所有的资金结算、交易查询、退款操作，都在这里进行。开发者需要从这里获取最重要的几个参数：商户号(MCHID)、API密钥(API Key)。
关键点：你需要把上述的“应用账号”（公众号或小程序）和“收款账号”（商户号）绑定授权。绑定后，应用才具备发起支付请求的资格。经常有人问：“我小程序后台配置了，为什么支付报错？” 第一反应就该去查绑定关系是不是真的成功了。
2. 参数三兄弟：AppID、MCHID、API Key
这三个参数是你代码里必须正确填写的“钥匙”。
AppID：来自你的应用（小程序或公众号），代表“谁在请求支付”。
MCHID：来自商户平台，代表“钱付给谁”。
API Key：来自商户平台，这是你自己设置的一串密钥。它是核心机密！用于生成支付签名，验证请求是不是你发出的。千万别泄露，也千万别在代码里写死然后传到公开的代码仓库（如GitHub）上，否则别人就能伪造你的请求盗刷。
常见坑：API Key在商户平台可以重置。如果你重置了，那么你服务器上所有用到旧Key的代码必须立刻更新成新Key，否则所有支付签名都会失败，支付全线崩溃。
3. 服务器配置：域名、证书和IP白名单
域名：支付后，微信会异步通知你的服务器支付结果（这叫“支付结果通知”或“异步回调”）。你用来接收这个通知的接口地址（URL），必须备案，且不能带端口号（通常用80或443）。开发时可以用内网穿透工具生成一个临时域名来测试，但上线必须用正式的、备案的域名。
SSL证书：上述的通知回调地址，必须是HTTPS开头。这意味着你的服务器必须部署有效的SSL证书（现在免费的很多）。HTTP的地址微信根本不认。
服务器IP白名单：在商户平台，你可以设置调用微信支付接口的服务器IP地址。如果你设置了，那么只有名单里的IP发出的请求才会被受理。这对于安全有好处，但千万记得，当你服务器迁移、扩容、换了IP，一定要来这里更新名单，不然支付请求会被直接拒绝。
开始写代码了，这里是问题高发区。
1. 签名（Sign）—— 万恶之源，也是万全之策
签名是支付对接里最麻烦、但最重要的安全环节。原理不复杂：把你所有要发送的参数，按字典序排序，用&和=拼接成字符串，最后拼接上你的API Key，再用MD5或HMAC-SHA256加密，得到一个签名字符串。微信收到请求后，会用同样的算法算一遍，如果两边签名一致，才认为请求是合法有效的。
为什么总出错？
参数漏了或多了一个空格：参与签名的参数，一个不能多，一个不能少。微信返回“签名错误”时，首先检查这个。有个调试技巧：把你生成签名的原串（拼接API Key之前的那个字符串）打印到日志里，和微信官方提供的签名校验工具生成的原串对比，一个字一个字符地对比，包括大小写。
API Key不对：上面提过，重置了没同步。
编码问题：参数值里如果有中文或特殊字符，要确保参与签名计算的编码和最终发送的编码一致（通常是UTF-8）。
签名的参数名不对：仔细看文档，有些参数不参与签名（如 sign 自己），有些必须参与（如 total_fee）。
2. 支付金额：单位为“分”，别搞成“元”
这是新手必掉坑。接口里传入的金额参数（如 total_fee），单位是分。如果你想收10元钱，就要传 1000。传成 10，用户就只付了1毛钱，后面退款、对账全是麻烦。在代码里强烈建议写注释，并且做乘以100的强制转换。
3. 异步通知（回调）—— 必须处理好
用户支付成功后，微信服务器会向你预设的notify_url发起一个POST请求，告诉你“这笔订单成功了”。这个机制至关重要，因为用户可能在支付成功后，由于网络等原因没收到你的前台提示。你的业务逻辑（比如发货、更新订单状态）应该主要依赖这个异步通知，而不是前台的同步返回。
处理回调的黄金法则：
快速回复：收到通知后，先进行签名验证（防止伪造），然后处理自己的业务逻辑（比如将订单状态改为“已支付”）。处理完成后，必须在5秒内回复微信一个固定的XML字符串：
业务逻辑要幂等：因为微信可能会重复通知（尽管你回复了，但在网络超时等极端情况下它可能没收到你的回复），所以你的处理逻辑必须是“幂等”的。简单说，就是同一笔支付通知，你处理一次和处理N次的结果应该一样。具体做法：接到通知后，先根据订单号查一下自己数据库，如果这笔订单已经是“已支付”状态，就直接回复成功，别再执行发货逻辑了。否则会造成重复发货。
日志要详尽：回调接口的入参、验签结果、处理过程、回复内容，必须打日志。这是出了问题时排查的唯一依据。
4. 前端与后端的配合
支付流程一般是：你的后台服务器用参数生成一个“预支付交易会话标识”（prepay_id），然后搭配一组按规则生成的签名参数，返回给前端（小程序/网页）。前端再调起微信支付的控件。
前端调起失败：检查传给前端控件的参数包（package 或 payment）格式是否正确，特别是 timeStamp 字段，前端要求是字符串类型，而后端生成的可能是数字，需要转换。
支付取消和失败：用户点了支付又取消，或者密码输错，这属于正常流程。你的前端需要监听这些状态，并给用户友好提示。不要把这些情况都当成系统错误。
代码上线，支付跑通了，但万里长征才走了第一步。日常维护才是考验。
1. 交易状态管理
一笔支付的生命周期有很多状态：未支付、用户支付中、支付成功、支付关闭、已退款等。你的系统状态必须和微信支付侧对齐。
主动查询是法宝：如果你的回调没收到（可能你的服务器当时短暂故障），或者你对一笔订单的状态不确定（比如用户说付了款但你这没记录），一定要用订单号主动调用微信支付的“查询订单”接口。这个接口能告诉你微信侧最真实的状态。不要单纯相信用户截图或自己数据库的缓存记录。
订单超时关闭：生成预支付订单时，可以设置一个有效时间（如2小时）。超时后，订单在微信侧会被关闭，用户无法再支付。你的系统也应该有定时任务，把超时未支付的订单状态更新为“已关闭”。
2. 退款处理
退款需要调用专门的退款接口。注意：
金额可部分退：可以小于原订单金额。
原路退回：钱会按用户原来支付的方式（零钱、银行卡）退回，周期不同。
注意证书：退款接口调用必须使用商户平台的API证书（和API Key不是一回事）。这个证书文件（.pem格式）需要从商户平台下载，妥善保管在服务器上，并在代码中配置好路径。这也是一个常见忘记配置导致调用失败的点。
异步通知：退款结果也有异步通知，处理方式和支付通知类似，地址可以单独配置。
3. 对账和风控
每日对账：商户平台每天会提供前一天的交易账单。你应该写一个自动化程序，每天下载账单，然后和你自己数据库的记录逐笔核对。目的是发现“单边账”（比如微信侧成功，你系统没记录；或者反过来）。发现后要及时用“查询订单”接口厘清，并人工补单或修正。
监控大额和异常订单：设置一些规则，比如短时间内同一用户/IP的频繁支付、金额异常大等，可能需要人工审核，以防盗刷或洗钱。
4. 监控和报警
支付是生命线，必须有监控。
回调失败报警：监控你的回调接口日志，如果连续出现验签失败、处理异常，必须报警。
失败率报警：监控支付调用（统一下单接口）的成功率，如果失败率突然飙升，立刻排查。
余额不足报警：商户平台里如果设置了自动提现，要监控账户余额，避免因余额不足导致退款失败。
文档是你最好的朋友，也是最坏的敌人：微信支付官方文档非常全，但也很庞杂。一定要看对应场景的最新版文档，不要用一年前的博客代码直接套。文档里的“注意事项”、“常见问题”章节，往往字字珠玑，能省你半天时间。
善用沙箱环境：在正式上线前，用官方提供的沙箱环境进行测试。它模拟支付流程，可以测试你的整个逻辑，而不用真的花钱。
日志！日志！日志！ 支付相关的所有接口，请求和响应，关键步骤的判断，必须打日志。出问题时，清晰的日志是唯一的救命稻草。
不要重复造轮子：如果你是主流语言（Java, PHP, Python, Node.js等）开发，网上有大量维护得不错的开源SDK。在充分理解其原理和安全性的基础上，使用这些SDK可以避免很多低级错误。当然，你要有能力在其出问题时进行调试和修复。
总之，微信支付对接是个细致活，考验收纳的是耐心、严谨和对安全的理解。前期准备越充分，开发时越仔细，上线后的维护就越轻松。希望这份攻略能帮你绕过那些坑，让支付流程顺畅如丝。
