平台收付通（分账）开发指引
更新时间：2023.08.23# 1. 接口规则
为了在保证支付安全的前提下，带给商户简单、一致且易用的开发体验，我们推出了全新的微信支付APIv3接口。该版本API的具体规则请参考APIv3接口规则。
# 2. 开发准备
# 2.1. 搭建和配置开发环境
为了帮助开发者调用开放接口，我们提供了JAVA、PHP、GO三种语言版本的开发库，封装了签名生成、签名验证、敏感信息加/解密、媒体文件上传 等基础功能（更多语言版本的开发库将在近期陆续提供）。
测试步骤：
1、根据自身开发语言，选择对应的开发库并构建项目，具体配置请参考下面链接的详细说明：
- wechatpay-java (opens new window)（推荐）、wechatpay-apache-httpclient (opens new window)，适用于Java开发者。
- 注：当前开发指引接口JAVA示例代码采用wechatpay-apache-httpclient版本。
- wechatpay-php (opens new window)（推荐）、wechatpay-guzzle-middleware (opens new window)，适用于PHP开发者。
- 注：当前开发指引接口PHP示例代码采用wechatpay-guzzle-middleware版本。
- wechatpay-go (opens new window)，适用于Go开发者。
更多资源可前往微信支付开发者社区 (opens new window)搜索查看。
2、创建加载商户私钥、加载平台证书、初始化httpClient的通用方法。
3、基于接口的示例代码，替换请求参数后可发起测试。
说明：
- 上面的开发库为微信支付官方开发库，其它没有审核或者控制下的第三方工具和库，微信支付不保证它们的安全性和可靠性。通过包管理工具引入SDK后，可根据下面每个接口的示例代码替换相关参数后进行快速测试。
- 开发者如果想详细了解签名生成、签名验证、敏感信息加/解密、媒体文件上传等常用方法的具体代码实现，可阅读下面的详细说明：
- 如想更详细的了解我们的接口规则，可查看我们的接口规则指引文档。
# 2.2. 业务开发配置-分账
需分账的订单，平台在下单时需预先打上分账标识“profit_sharing”，详细可查看各场景下单API（普通支付下单/合单支付下单API）。
# 3. 快速接入
# 3.1. 业务流程图-分账
重要步骤说明：
步骤1 平台通过添加分账接收方API添加需要分账的分账对象（接收方）。
步骤2 平台预先在合单支付/普通支付下单API接口中上传分账标识“profit_sharing”，待订单完成支付后即可调用请求分账API接口发起分账请求。
步骤3 分账完成后，微信会通过分账动账通知API接口，主动通知商户。商户如有需要，可以通过查询分账结果API接口，主动查询分账结果。
步骤4 分账后若产生退款，则需先调用请求分账回退API 接口，请求将已经分给分账方的资金回退，再处理退款。
步骤5 分账回退完成后，微信同样会通过分账动账通知API接口，主动通知商户。商户也可以通过查询分账回退结果API接口，主动查询分账结果。
步骤6： 分账结束后，商户需调用完结分账API接口结束分账订单。
# 3.2. API接入-分账
本文档展示了如何使用微信支付服务端 SDK 快速接入平台收付通产品，完成与微信支付对接的部分。
注意
- 文档中的代码示例是用来阐述 API 基本使用方法，代码中的示例参数需替换成商户自己账号及请求参数才能跑通。
- 以下接入步骤仅提供参考，请商户结合自身业务需求进行评估、修改。
# 3.2.1.【服务端】添加分账接收方
步骤说明： 平台可通过此接口添加分账接收方，建立分账接收方列表。后续通过发起分账请求，将平台下的二级商户结算后的资金，分给分账接收方列表中具体的分账接收方。
更多参数、响应详情及错误码请参见添加分账接收方API接口文档。
# 3.2.2.【服务端】请求分账
步骤说明： 平台，如有订单需要进行分账，可通过此接口完成。
更多参数、响应详情及错误码请参见请求分账API接口文档。
# 3.2.3.【服务端】分账动账通知
步骤说明： 此功能仅针对分账接收方，当分账动账金额发生变动时，微信会把相关变动结果发送给需要实时关注的分账接收方。
注意
- 支付结果通知是以POST 方法访问商户设置的通知URL，通知的数据以JSON 格式通过请求主体（BODY）传输。通知的数据包括了加密的支付结果详情。
- 加密不能保证通知请求来自微信。微信会对发送给商户的通知进行签名，并将签名值放在通知的HTTP头Wechatpay-Signature。商户应当验证签名，以确认请求来自微信，而不是其他的第三方。签名验证的算法请参考 《微信支付API v3签名验证》。
- 支付通知HTTP应答码为200或204才会当作正常接收，当回调处理异常时，应答的HTTP状态码应为500，或者4xx。
- 商户成功接收到回调通知后应返回成功的HTTP应答码为200或204。
- 同样的通知可能会多次发送给商户系统。商户系统必须能够正确处理重复的通知。 推荐的做法是，当商户系统收到通知进行处理时，先检查对应业务数据的状态，并判断该通知是否已经处理。如果未处理，则再进行处理；如果已处理，则直接返回结果成功。在对业务数据进行状态检查和处理之前，要采用数据锁进行并发控制，以避免函数重入造成的数据混乱。
更多参数、响应详情及错误码请参见分账动账通知API接口文档。
# 3.2.4. 【服务端】查询分账结果
步骤说明： 平台可通过此接口实时关注订单的分账请求和分账完结情况。
更多参数、响应详情及错误码请参见 查询分账结果API接口文档。
# 3.2.5. 【服务端】请求分账回退
步骤说明： 订单已经分账，在退款时，可以先调此接口，将已分账的资金从分账接收方的账户回退给分账方，再发起退款。
更多参数、响应详情及错误码请参见请求分账回退API 接口文档。
# 3.2.6. 【服务端】查询分账回退结果
步骤说明： 商户需要核实回退结果，可调用此接口查询回退结果;如果分账回退接口返回状态为处理中，可调用此接口查询回退结果。
更多参数、响应详情及错误码请参见查询分账回退结果API 接口文档。
# 3.2.7. 【服务端】完结分账
步骤说明： 不需要进行分账的订单，可直接调用本接口将订单的金额全部解冻给二级商户。
更多参数、响应详情及错误码请参见完结分账API接口文档。
# 3.2.8. 【服务端】查询订单剩余待分金额
步骤说明： 分账接口支持对一笔订单进行多次分账，在这过程中，你可以使用该接口查询订单剩余的可进行分账的金额。
更多参数、响应详情及错误码请参见查询订单剩余待分金额API接口文档。
# 3.2.9. 【服务端】删除分账接收方
步骤说明： 平台发起删除分账接收方请求。删除后，不支持将平台下二级商户结算后的资金，分到该分账接收方。
更多参数、响应详情及错误码请参见 删除分账接收方API接口文档。
# 4. 常见问题
# Q:平台收付通分账调用“请求分账回退接口”返回：可用余额不足，请充值后重新发起
A：“回退商户号”的账户可用余额不足，需充值后再原单重试才能回退成功。
# Q:平台收付通分账调用“请求分账回退接口”返回：可用余额不足，请充值后重新发起。这个时候，调用“查询分账回退结果API”却返回：PROCESSING（处理中），这个逻辑是正常的吗
A：是正常的，逻辑就是这样的。这种情况，商户可以按照提示要求，提醒“回退商户号”充值后再原单重试即可回退成功。
# Q:平台收付通分账调用“请求分账回退接口”返回：PROCESSING（处理中），什么情况会返回这种状态
A：请参考以下几点：
- 网络抖动导致请求中断。
- 商户账户资金转账频繁，导致回退在排队时超时。
# Q:平台收付通分账调用“查询分账回退结果接口”返回：TIME_OUT_CLOSED
A：TIME_OUT_CLOSED是fail状态了，也就是处于最终态，是不需要重试的。状态是SUCCESS也同理，也是最终态，不需要重试。返回TIME_OUT_CLOSED时可更换一个回退单，重新分账回退一次即可。
# Q:平台收付通分账调用“请求分账接口”返回：分账补贴还未到账，不能受理分账
A：报这个错误，是因为支付的订单在基础下单里面传了参数“补差金额：subsidy_amount”，传这个参数后，需要调用“请求补差API”完成补差，然后再调用“请求分账接口”即可正常分账。
