需确认模式
更新时间：2024.03.06# 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. 搭建和配置开发环境
- 微信支付分的相关配置参数在商户入驻的过程中都已经配置完成（前往查看配置相关内容），例如授权结果回调URL、service_notify_url、测试白名单、免确认订单模式的权限等。
- 如果发现配置信息有误，请主动联系微信支付分运营同学协助修改，或者_点击右侧导航栏进入在线技术客服进行技术咨询。
# 3. 快速接入(需确认模式)
# 3.1. 业务流程图
重点步骤说明：
步骤1 用户在商户侧下单，商户调用后台接口创建支付分订单，通过接口返回获得跳转微信支付分小程序进行订单确认的必填参数“package”。
我们通过此接口来创建支付分订单：创建支付分订单API
- 入参“need_user_confirm”，取值请选择 “true”；
- 入参“risk_fund:name”，取值请选择【先免模式】中的枚举值。
步骤2 调用前端方法跳转至微信，让用户完成确认订单操作
我们通过以下前端方法可调起微信客户端（注意区分场景）：
步骤3 用户确认订单完成，商户系统将收到确认订单回调通知，此时可为用户提供服务；
我们通过以下接口将用户确认订单信息回调通知给商户系统：
在用户确认订单过程中可能出现长时间未收到回调、用户确认失败等情况，商户可先通过后台接口查询订单状态：
根据查询到的订单状态结果，商户可决定是否需要取消当前订单，后台接口为：
步骤4 用户服务结束，商户通过后台接口完结支付分订单；
调用完结支付分订单API接口后，微信支付分就会发起对用户的扣款，但是在用户扣款过程中可能会出现一些特殊情况，下面列举了几种特殊情况以及对应的处理方法，供大家参考：
请求：
- 情况一：扣款过程中，发现扣款金额有误（注意：此时需要订单为“待支付”状态）
处理方法1：调用修改订单金额接口修改订单金额，系统将按照修改后的金额发起用户扣款
处理方法2：调用取消支付分订单接口取消待支付的支付分订单
- 情况二：扣款过程中，用户通过其它方式完成了支付，希望微信支付分停止继续扣款
处理方法：商户调用同步服务订单信息接口将订单支付成功状态同步给微信支付分，微信支付分将停止继续扣款的操作
步骤5 收到用户扣款成功通知，业务流程结束
通过支付成功回调通知API接口可以获取到用户扣款成功的通知，同时，商户也可以根据情况通过查询支付分订单API接口主动查询扣款情况。
- 如订单状态state=DONE，且收款状态collection.state=USER_PAID，代表扣款成功
- 如订单状态state=DOING，state_description=MCH_COMPLETE，且收款状态collection.state=USER_PAYING，代表扣款进行中
如遇到网络、服务器等原因造成无法正常接收扣款成功通知，一般有两种解决方法：
- 主动查单，通过查询支付分订单API 接口主动查询扣款情况
- 次日对账，通过申请交易账单API接口申请交易账单，再通过后台接口下载账单API下载交易账单
# 3.2. API接入（含示例代码）
本文档展示了如何使用微信支付服务端 SDK 快速接入微信支付分产品，完成与微信支付对接的部分。
注意
- 文档中的代码示例是用来阐述 API 基本使用方法，代码中的示例参数需替换成商户自己账号及请求参数才能跑通。
- 以下接入步骤仅提供参考，请商户结合自身业务需求进行评估、修改。
# 3.2.1. 【服务端】创建支付分订单
步骤说明： 完成用户授权后，即可创建支付分订单，为用户提供服务了。
重要参数说明：
- 入参“need_user_confirm”，取值请选择 “true”；
- 入参“risk_fund:name”，取值请选择【先免模式】中的枚举值。
更多参数、响应详情及错误码请参见创建支付分订单API接口文档。
# 3.2.2. 【客户端】跳转确认订单页
微信支付根据用户不同的使用场景（App、小程序、微信内H5）分别提供了对应跳转确认订单页的方法，请根据场景进行选择，详见跳转确认订单页API文档
# 3.2.3. 【服务端】确认订单回调通知
步骤说明： 当用户确认订单时，微信会把相关信息异步回调的方式通知商户，商户需要接收处理，并按文档规范返回应答
注意
- 支付结果通知是以POST 方法访问商户设置的通知URL，通知的数据以JSON 格式通过请求主体（BODY）传输。通知的数据包括了加密的支付结果详情
- 加密不能保证通知请求来自微信。微信会对发送给商户的通知进行签名，并将签名值放在通知的HTTP头Wechatpay-Signature。商户应当验证签名，以确认请求来自微信，而不是其他的第三方。签名验证的算法请参考 《微信支付API v3签名验证》。
- 支付通知HTTP应答码为200或204才会当作正常接收，当回调处理异常时，应答的HTTP状态码应为500，或者4xx
- 商户成功接收到回调通知后应返回成功的HTTP应答码为200或204
- 同样的通知可能会多次发送给商户系统。商户系统必须能够正确处理重复的通知。 推荐的做法是，当商户系统收到通知进行处理时，先检查对应业务数据的状态，并判断该通知是否已经处理。如果未处理，则再进行处理；如果已处理，则直接返回结果成功。在对业务数据进行状态检查和处理之前，要采用数据锁进行并发控制，以避免函数重入造成的数据混乱。
- 如果在所有通知频率(4小时)后没有收到微信侧回调，商户应调用查询订单接口确认订单状态。
更多参数、响应详情及错误码请参见确认订单回调通知API接口文档。
# 3.2.4. 【服务端】查询支付分订单
步骤说明： 一般在创建订单后、订单完结成功后等关键流程中，商户可能有知晓订单状态的需求，此时即可通过该接口查询订单状态。
更多参数、响应详情及错误码请参见 查询支付分订单API接口文档。
# 3.2.5. 【服务端】取消支付分订单
步骤说明： 订单为以下状态时可以取消订单：CREATED（已创单）、DOING（进行中）（包括商户完结支付分订单后，且支付分订单收款状态为待支付USER_PAYING）。
更多参数、响应详情及错误码请参见 取消支付分订单API接口文档。
# 3.2.6. 【服务端】完结支付分订单
步骤说明： 用户服务结束后，商户通过请求完结支付分订单接口，通过微信支付分进行用户扣款操作。
更多参数、响应详情及错误码请参见完结支付分订单API接口文档。
# 3.2.7. 【服务端】修改订单金额
步骤说明： 在用户扣款成功前、完结订单后（即订单状态为“待支付”），如需修改订单支付金额，可通过此接口进行订单金额修改。修改成功后，微信支付将按照修改后的金额进行用户扣款。
更多参数、响应详情及错误码请参见修改订单金额API接口文档。
# 3.2.8. 【服务端】同步服务订单信息
步骤说明： 由于一些原因，用户与商户达成线下支付或者其他支付方式支付的协议，商户可通过此接口告知微信支付该笔订单无需继续扣款，微信支付在接到此信息后将不再发起用户扣款。
更多参数、响应详情及错误码请参见 同步服务订单信息API接口文档。
# 3.2.9. 【服务端】申请交易账单
步骤说明： 微信支付按天提供交易账单文件，商户可以通过该接口获取账单文件的下载地址。
更多参数、响应详情及错误码请参见 申请交易账单API接口文档。
# 3.2.10. 【服务端】下载交易账单
步骤说明： 通过申请交易账单接口获取到账单下载地址（download_url）后，再通过该接口获取到对应的账单文件，文件内包含交易相关的金额、时间、营销等信息，供商户核对订单、退款、银行到账等情况
注意
- 账单文件的下载地址的有效时间为30s
- 强烈建议商户将实际账单文件的哈希值和之前从接口获取到的哈希值进行比对，以确认数据的完整性
更多参数、响应详情及错误码请参见 下载账单API接口文档。
# 3.2.11. 【服务端】支付成功回调通知
步骤说明： 当用户完成支付，微信会把相关支付结果将通过异步回调的方式通知商户，商户需要接收处理，并按文档规范返回应答。
注意
- 支付结果通知是以POST 方法访问商户设置的通知URL，通知的数据以JSON 格式通过请求主体（BODY）传输。通知的数据包括了加密的支付结果详情
- 加密不能保证通知请求来自微信。微信会对发送给商户的通知进行签名，并将签名值放在通知的HTTP头Wechatpay-Signature。商户应当验证签名，以确认请求来自微信，而不是其他的第三方。签名验证的算法请参考 《微信支付API v3签名验证》。
- 支付通知HTTP应答码为200或204才会当作正常接收，当回调处理异常时，应答的HTTP状态码应为500，或者4xx
- 商户成功接收到回调通知后应返回成功的HTTP应答码为200或204
- 同样的通知可能会多次发送给商户系统。商户系统必须能够正确处理重复的通知。 推荐的做法是，当商户系统收到通知进行处理时，先检查对应业务数据的状态，并判断该通知是否已经处理。如果未处理，则再进行处理；如果已处理，则直接返回结果成功。在对业务数据进行状态检查和处理之前，要采用数据锁进行并发控制，以避免函数重入造成的数据混乱。
- 如果在所有通知频率(4小时)后没有收到微信侧回调，商户应调用查询订单接口确认订单状态。
更多参数、响应详情及错误码请参见 支付成功回调通知API接口文档。
# 3.2.12. 【客户端】跳转订单详情
微信支付根据用户不同的使用场景（App、小程序、微信内H5）分别提供了对应跳转订单详情页的方法，请根据场景进行选择，详见跳转订单详情页API文档。
# 4. 常见问题
# Q：需确认订单模式，同一个用户可以下多少笔免押订单，如果该用户有未完结的支付分订单，会不会影响用户下一笔订单免押
A：同一个用户可以确认免押订单进行中的笔数是3笔（未完结&未支付的订单笔数，产品策略，可能会调整）；如果用户进行中的订单超过3笔，则需要进行押金支付,如果有任何1笔待支付的订单，都是需要去支付押金的。
# Q：商户小程序跳转支付分小程序（详情页，确认页）报错“未通过申请，当前服务未上线”
A：检查测试微信是否开通白名单，提供服务ID和微信号联系运营开通白名单
# Q：创建支付分订单返回{"code":"NO_AUTH","message":"商户暂无权限使用此服务"}
A：
- 检查商户号和AppID是否配置了通用化接口权限，可以联系微信侧运营确认和配置通用化接口权限
- 如果商户开通的是免确认订单权限，创建订单时need_user_confirm只能传false，如果商户开通的是含确认订单权限，创建订单时need_user_confirm只能传true
# Q：创建支付分订单返回{"code":"PARAM_ERROR","message":"订单风险金额名称不符合要求"}
A：检查商户号开通的是哪种模式的权限，需确认模式可以使用先免模式与先享模式，免确认模式只能使用先享模式
# Q：调用支付分创单接口报错返回“mch_id和AppID未绑定”如何处理？
A：请商户自行检查mch_id和AppID是否有对应的绑定关系。绑定步骤参考“商家商户号与AppID账号关联管理 (opens new window)”。
