开发指引
更新时间：2025.01.141. 接口规则
为了在保证支付安全的前提下，带给商户简单、一致且易用的开发体验，我们推出了全新的微信支付APIv3接口。该版本API的具体规则请参考APIv3接口规则。
2. 开发准备
2.1. 搭建和配置开发环境
开发者应当依据自身的编程语言来构建并配置相应的开发环境。
2.2. 接口体验
如果开发者使用过PostmanAPI的调试，建议在正式开发之前，使用 Postman签名脚本 进行接口体验。
3. 商家转账业务接入说明
3.1. 业务流程图
3.2. 关键步骤说明
第一步：发起商家转账到零钱
1、调用接口前，开发者需要参考 接入前准备 确认已完成权限开通和产品配置，特别是关于API发起转账的相关配置一定要正确。
2、商户发起商家转账到零钱，先调用《发起批量转账》接口发起批次转账请求，受理成功将返回批次单号，此时并不代表转账成功。
3、当返回错误码为“SYSTEM_ERROR”时，请不要更换商家批次单号，一定要使用原商家批次单号及原参数重试，否则可能造成重复转账等资金风险。
4、受理成功后，在单据创建时间的3个自然日内使用同样批次单信息请求该接口，均返回应答码“200 OK”及对应的应答参数。
第二步：查询转账批次状态
1、使用API接口只支持查询最近30天内的转账批次单状态，30天之前的转账批次单请登录商户平台查询。
2、当发起商家转账到零钱请求受理成功之后，需间隔1分钟以上才可调用《通过微信批次单号查询批次单》、《通过商家批次单号查询批次单》接口来查询批次转账状态，若发起转账请求后立即查询，有可能查询到“转账批次单不存在”。
3、当查询到的批次单状态为：WAIT_PAY 时， 表示「付款验密人」需要到「微信支付商户助手」输入安全密码验证，24小时内未完成验证，自动关闭批次单。
4、当查询到批次单状态为FINISHED(已完成),才可进行下一步，查询转账明细状态。
第三步：查询转账明细状态
当查询到批次单状态为FINISHED(已完成)，才可调用《通过微信明细单号查询明细单》、《通过商家明细单号查询明细单》接口进行转账明细查询。
第四步：申请下载电子回单(按需使用)
1、发起转账时传入了收款用户姓名，才支持申请电子回单。
2、支持受理2年内的转账批次电子回单和转账明细电子回单。
3、仅支持已完成状态且至少有一笔成功记录的批次获取转账批次电子回单(不满足条件返回 400 INVALID_REQUEST)；
4、仅支持转账已完成的明细单申请电子回单（不满足条件返回 400 PARAM_ERROR）；
5、详情参考 申请转账账单电子回单接口、查询转账账单电子回单接口、申请转账明细账单电子回单、查询转账明细账单电子回单、下载电子回单。
3.3. 明细失败原因说明
在查询商家转账明细单号时，如果转账失败则有明细失败原因，说明如下：
明细失败原因 | 说明 |
|---|---|
| 该用户账户被冻结 |
| 该用户账户不存在 |
| 银行卡已被销户、冻结、作废、挂失等致无法入账 |
| 登记的银行名称或分支行信息有误 |
| 银行卡户名或卡号有误 |
| 银行卡属二/三类卡，达到收款限额无法入账 |
| 用户收款卡错误，请核实信息 |
| 银行卡状态异常，无法入账 |
| 超出用户月转账收款限额，本月不支持继续向该用户付款 |
| 用户账户存在风险收款受限，本月不支持继续向该用户付款 |
| 超过用户日收款次数，核实产品设置是否准确 |
| 超过用户日收款额度，核实产品设置是否准确 |
| 转账金额超过预约金额范围，请检查 |
| 收款人身份证校验不通过，请核实信息 |
| 商户员工（转账验密人）已驳回转账 |
| 商户员工（转账验密人）超时未验密 |
| 收款人姓名校验不通过，请核实信息 |
| OpenID格式错误或者不属于商家公众账号 |
| 其它失败原因 |
| 超过系统重试期，系统自动关闭 |
| 用户账户收款异常，请联系用户完善其在微信支付的身份信息以继续收款 |
| 商户账户付款受限，可前往商户平台获取解除功能限制指引 |
| 未开通该权限或权限被冻结，请核实产品权限状态 |
| 用户账户收款受限，请引导用户在微信支付查看详情 |
| 收款人未实名认证，需要用户完成微信实名认证 |
| 请前往商户平台-商家转账到零钱-前往功能-转账场景中添加 |
| 转账信息，如用户OpenID等参数，与预约时传入的信息不一致，请检查 |
| 该预约单的转账场景与发起转账时传入的不同，请检查 |
| 预约转账单状态异常，请检查 |
| 超过用户单笔收款额度，核实产品设置是否准确 |
| 转账备注设置失败， 请调整后重新再试 |
| 该笔转账可能存在风险，已被微信拦截 |
| 你尚未获取该转账场景，请确认转账场景ID是否正确 |
| 该转账场景暂不可用，请确认转账场景ID是否正确 |
进一步阅读
