免确认模式
更新时间：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 用户在商户侧下单购买产品或服务，此时，我们需要先对用户的授权状态进行查询
查询用户授权状态的两种方法：
用户授权状态一共分三种：
UNAVAILABLE：用户未授权服务
AVAILABLE：用户已授权服务
UNBINDUSER：未绑定用户
当查询到用户授权状态为UNAVAILABLE、UNBINDUSER时，请前往步骤二：引导用户开启服务；
当查询到用户授权状态为AVAILABLE时，请前往步骤三：创建支付分订单；
步骤2 引导用户开启授权服务
开启授权有两步操作，第一步：调用后台接口进行预授权，第二步：调用前端方法跳转进入微信中让用户进行授权。
- （第一步）预授权后台接口文档详见：商户预授权API
- （第二步）跳转进入微信授权根据用户使用场景从以下三种方法选择其一：App场景调起支付分-授权服务、JSAPI场景调起支付分-授权服务、小程序调起支付分-授权服务
请求开启授权之后，我们需要确认开启授权是否成功，共有两种方法：
1、通过接口主动查询(未及时收到用户授权成功通知情况下且用户已回到商家授权页面时商户侧主动查询。)——查询与用户授权记录（OpenID）、查询与用户授权记录（授权协议号）
2、等待支付分的异步通知——开启/解除授权结果回调通知
若获取到用户的授权状态为AVAILABLE：用户已授权服务，则前往步骤三；
若获取到用户的授权状态为UNAVAILABLE-用户未授权服务、UNBINDUSER-未绑定用户，则商户可根据业务需要选择继续查询或者结束支付分流程，进入商户自己的业务流程。
步骤3 创建支付分订单
我们通过创建支付分订单API接口创建一笔待支付的支付分订单。
请求：
入参“need_user_confirm”，取值请选择 “false”；
入参“risk_fund:name”，取值请选择【先享模式】中的枚举值。
返回：
- 若接口返回state=DOING：表示商户创建服务订单成功，可前往步骤四；
- 若接口返回state≠DOING：表示商户创建服务订单失败，商户可根据实际返回内容提示选择重新创建或者结束支付分流程，进入商户自己的业务流程；
创建服务订单失败原因会在接口返回字段“message”中返回，主要失败原因有两种：
- 存在未完结订单
- 综合评估不通过，建议商户稍后重试或者使用其他渠道支付
步骤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. 【服务端】查询用户授权关系
步骤说明： 创建支付分订单的前提是用户必须有授权关系，所以在免确认模式下，我们最先要做的就是确保用户是已授权状态。目前提供了使用OpenID和授权协议号两种条件进行查询的方式。下面以查询用户授权记录（OpenID）举例接口调用方式。
重要入参说明：
- 查询条件参数OpenID或者授权协议号都是在接口URL中传递的，请勿传到body中去。
更多参数、响应详情及错误码请参见查询用户授权记录（OpenID）接口文档。
# 3.2.2. 【服务端】请求预授权接口
步骤说明： 创建支付分订单的前提是用户必须有授权关系，所以在免确认模式下，我们最先要做的就是确保用户是已授权状态。通过商户预授权接口获取跳转用户授权页必填参数“预授权token”。
重要入参说明：
- 完成用户授权需要两步操作，预授权接口仅是为获取关键参数“预授权token”，商户还需引导用户跳转到微信授权页进行授权操作。
更多参数、响应详情及错误码请参见 商户预授权API接口文档。
# 3.2.3. 【客户端】开启授权服务
步骤说明： 通过商户预授权接口获取到跳转用户授权页必填参数“预授权token”后，即可通过前端方法跳转到微信客户端，让用户开启授权服务。前端跳转方法请根据用户实际使用场景（App、小程序、微信内H5）来选择。
# 3.2.4. 【服务端】开启/解除授权服务回调通知
步骤说明： 当用户授权或解约服务成功时，微信会把相关信息异步回调的方式通知商户，商户需要接收处理，并按文档规范返回应答
注意
- 支付结果通知是以POST 方法访问商户设置的通知URL，通知的数据以JSON 格式通过请求主体（BODY）传输。通知的数据包括了加密的支付结果详情
- 加密不能保证通知请求来自微信。微信会对发送给商户的通知进行签名，并将签名值放在通知的HTTP头Wechatpay-Signature。商户应当验证签名，以确认请求来自微信，而不是其他的第三方。签名验证的算法请参考 《微信支付API v3签名验证》。
- 支付通知HTTP应答码为200或204才会当作正常接收，当回调处理异常时，应答的HTTP状态码应为500，或者4xx
- 商户成功接收到回调通知后应返回成功的HTTP应答码为200或204
- 同样的通知可能会多次发送给商户系统。商户系统必须能够正确处理重复的通知。 推荐的做法是，当商户系统收到通知进行处理时，先检查对应业务数据的状态，并判断该通知是否已经处理。如果未处理，则再进行处理；如果已处理，则直接返回结果成功。在对业务数据进行状态检查和处理之前，要采用数据锁进行并发控制，以避免函数重入造成的数据混乱。
- 如果在所有通知频率(4小时)后没有收到微信侧回调，商户应调用查询订单接口确认订单状态。
更多参数、响应详情及错误码请参见开启/解除授权服务回调通知API接口文档。
# 3.2.5. 【服务端】创建支付分订单
步骤说明： 完成用户授权后，即可创建支付分订单，为用户提供服务了。
重要参数说明：
- 入参“need_user_confirm”，取值请选择 “false”；
- 入参“risk_fund:name”，取值请选择【先享模式】中的枚举值。
更多参数、响应详情及错误码请参见 创建支付分订单API接口文档。
# 3.2.6. 【服务端】完结支付分订单
步骤说明： 用户服务结束后，商户通过请求完结支付分订单接口，通过微信支付分进行用户扣款操作。
更多参数、响应详情及错误码请参见 完结支付分订单API接口文档。
# 3.2.7. 【服务端】修改订单金额
步骤说明： 在用户扣款成功前、完结订单后（即订单状态为“待支付”），如需修改订单支付金额，可通过此接口进行订单金额修改。修改成功后，微信支付将按照修改后的金额进行用户扣款。
更多参数、响应详情及错误码请参见修改订单金额API接口文档。
# 3.2.8. 【服务端】取消支付分订单
步骤说明： 订单为以下状态时可以取消订单：CREATED（已创单）、DOING（进行中）（包括商户完结支付分订单后，且支付分订单收款状态为待支付USER_PAYING）。
更多参数、响应详情及错误码请参见取消支付分订单API接口文档。
# 3.2.9. 【服务端】同步服务订单信息
步骤说明： 由于一些原因，用户与商户达成线下支付或者其他支付方式支付的协议，商户可通过此接口告知微信支付该笔订单无需继续扣款，微信支付在接到此信息后将不再发起用户扣款。
更多参数、响应详情及错误码请参见 同步服务订单信息API接口文档。
# 3.2.10. 【服务端】查询支付分订单
步骤说明： 一般在创建订单后、订单完结成功后等关键流程中，商户可能有知晓订单状态的需求，此时即可通过该接口查询订单状态。
更多参数、响应详情及错误码请参见 查询支付分订单API接口文档。
# 3.2.11. 【服务端】申请交易账单
步骤说明： 微信支付按天提供交易账单文件，商户可以通过该接口获取账单文件的下载地址。
更多参数、响应详情及错误码请参见 申请交易账单API接口文档。
# 3.2.12. 【服务端】下载交易账单
步骤说明： 通过申请交易账单接口获取到账单下载地址（download_url）后，再通过该接口获取到对应的账单文件，文件内包含交易相关的金额、时间、营销等信息，供商户核对订单、退款、银行到账等情况
注意
- 账单文件的下载地址的有效时间为30s
- 强烈建议商户将实际账单文件的哈希值和之前从接口获取到的哈希值进行比对，以确认数据的完整性
更多参数、响应详情及错误码请参见 下载账单API接口文档。
# 3.2.13. 【服务端】支付成功回调通知
步骤说明： 当用户完成支付，微信会把相关支付结果将通过异步回调的方式通知商户，商户需要接收处理，并按文档规范返回应答
注意
- 支付结果通知是以POST 方法访问商户设置的通知URL，通知的数据以JSON 格式通过请求主体（BODY）传输。通知的数据包括了加密的支付结果详情
- 加密不能保证通知请求来自微信。微信会对发送给商户的通知进行签名，并将签名值放在通知的HTTP头Wechatpay-Signature。商户应当验证签名，以确认请求来自微信，而不是其他的第三方。签名验证的算法请参考 《微信支付API v3签名验证》。
- 支付通知HTTP应答码为200或204才会当作正常接收，当回调处理异常时，应答的HTTP状态码应为500，或者4xx
- 商户成功接收到回调通知后应返回成功的HTTP应答码为200或204
- 同样的通知可能会多次发送给商户系统。商户系统必须能够正确处理重复的通知。 推荐的做法是，当商户系统收到通知进行处理时，先检查对应业务数据的状态，并判断该通知是否已经处理。如果未处理，则再进行处理；如果已处理，则直接返回结果成功。在对业务数据进行状态检查和处理之前，要采用数据锁进行并发控制，以避免函数重入造成的数据混乱。
- 如果在所有通知频率(4小时)后没有收到微信侧回调，商户应调用查询订单接口确认订单状态。
更多参数、响应详情及错误码请参见 支付成功回调通知API接口文档。
# 3.2.14. 【服务端】解除用户授权关系
步骤说明： 如果用户或者商户有解除授权关系的需求，可通过该接口进行“解约”。我们提供了两种解约方式：使用签约协议号和使用用户OpenID进行解约，下面我们以使用用户OpenID解约为例，进行代码演示。
更多参数、响应详情及错误码请参见 解除用户授权关系API接口文档。
# 3.2.15. 【客户端】跳转订单详情
微信支付根据用户不同的使用场景（App、小程序、微信内H5）分别提供了对应跳转订单详情页的方法，请根据场景进行选择，详见跳转订单详情页API文档
# 4. 常见问题
# 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：免确认订单模式创建支付分订单报错{"code":"INVALID_REQUEST","message":"综合评估不通过"}是什么原因
A：表示免确认流程创单用户被不对外风控拦截
# Q：调用支付分创单接口报错返回“mch_id和AppID未绑定”如何处理？
A：请商户自行检查mch_id和AppID是否有对应的绑定关系。绑定步骤参考:商家商户号与AppID账号关联管理 (opens new window)
