微信支付API对接实战教程与安全配置

微信支付V3接口概述与前期配置

微信支付API对接是接入移动支付的关键环节。当前微信主推V3版本接口，在安全性和规范性上显著提升。开始对接前需在微信商户平台完成商户号注册，绑定小程序或公众号，获取商户API证书和APIv3密钥。V3接口采用HTTPS通信，要求服务端安装微信支付平台证书用于验签。证书可通过平台证书接口自动获取或手动下载。配置时需区分商户证书和平台证书，前者用于请求签名，后者用于验证响应签名。V3接口的报文格式统一为JSON，相比V2的XML格式更易于解析和处理。接口错误码体系也更加完善，开发者可根据错误码精确定位问题。

签名生成与请求构造

微信支付V3的签名机制是对接重点。签名串构造规则为HTTP请求方式、换行、URL路径、换行、时间戳、换行、随机串、换行、请求主体。用商户私钥对签名串进行SHA256withRSA签名，结果放入Authorization请求头。请求头还需包含商户号、证书序列号等信息。金额单位为分，订单号需在商户号下唯一。统一下单返回预支付交易会话标识，前端据此调起支付控件。对于小程序支付场景，还需将预支付标识传给前端调用wx.requestPayment接口。请求构造中需注意参数类型和格式严格按照文档要求，否则会导致签名验证不通过。时间戳需为秒级，随机串建议使用UUID格式。

支付回调通知的接收与解密

微信支付回调采用加密传输，是V3版本的重要安全特性。微信向回调地址发送POST请求，报文含加密数据和资源密钥。解密流程为用APIv3密钥对resource.ciphertext进行AES-256-GCM解密，获得原始通知内容。解密后验证商户号、订单号、金额与本地订单是否一致，确认后更新状态并返回JSON格式应答，HTTP状态码为200。若未正确应答，微信会重复发送通知，最大重试八次，间隔从十五秒递增到二十四小时。解密过程中需注意associated_data和nonce参数的正确使用，任何一项错误都会导致解密失败。建议在解密失败时记录完整的原始报文，便于后续排查。

退款查询接口与安全实践

退款接口需传入原订单号、退款单号、退款金额和原订单金额，退款单号在商户号下唯一。退款同样支持异步通知，处理逻辑与支付回调类似。订单查询接口用于主动确认支付状态，建议在回调未及时收到时通过定时任务轮询。查询需注意频率控制，避免触发限流。安全方面，APIv3密钥和商户私钥应存储在密钥管理系统中，禁止硬编码。日志需脱敏处理。分布式部署需处理并发回调幂等性，通过数据库唯一索引或分布式锁防止重复处理。定期轮换API密钥并确保新旧密钥平滑过渡。退款接口还需注意退款资金来源的配置，可指定从可用余额或未结算资金中扣除。