1. 接口规则

为了在保证支付安全的前提下，带给商户简单、一致且易用的开发体验，我们推出了全新的微信支付APIv3接口。该版本API的具体规则请参考APIv3接口规则。

2. 开发准备

2.1. 搭建和配置开发环境

开发者应当依据自身的编程语言来构建并配置相应的开发环境。

2.2. 搭建和配置开发环境

1. 微信支付分的相关配置参数在商户入驻的过程中都已经配置完成（前往查看配置相关内容），例如开通支付分权限，商户入驻，服务开通按计划确认权限等。
2. 如果发现配置信息有误，请主动联系微信支付分运营同学协助修改，或者_点击右侧导航栏进入在线技术客服进行技术咨询。

3. 快速接入

3.1. 业务流程图

重点步骤说明：

步骤1 商户创建一个支付分计划，该计划包含了一组为用户提供的服务，方便商家让用户一次性对整个计划的所有扣费内容完成确认

调用创建支付分计划接口完成本步骤

1. 调用接口时请确保传入的服务ID有效，对应服务已经开通了支付分按计划确认权限，商户已经完成服务入驻
2. 支付分计划有效期(单位天)和支付分计划扣费次数确保小于等于服务规定的最大支付分计划有效期(单位天)和支付分计划扣费次数
3. 支付分计划明细列表中计划明细数量确保等于支付分计划扣费次数
4. 支付分系统会根据支付分计划明细列表中的计划明细顺序给计划明细按顺序从1开始编号，每个计划明细请确保计划明细原支付金额(单位分)大于等于计划明细实际支付金额(单位分)，且每个计划明细的计划明细实际支付金额(单位分)需要小于等于按顺序的上一个计划明细

步骤2 用户在商户侧下单购买计划时，商户发起支付分计划用户签约，此时首先我们需要创建一个支付分用户的签约计划

在创建支付分用户的签约计划前，请确保对应的支付分计划已经创建且没有被终止，可以通过查询支付分计划接口查询并确认计划状态

支付分计划状态一共分两种

• NORMAL: 计划正常进行中，可以签约
• STOP: 计划停止，无法签约，已签约的计划可以继续完成服务

调用创建支付分用户的签约计划接口给指定用户创建一个待签约的支付分计划

1. 调用接口时请确保传入的服务ID有效，对应服务已经开通了支付分按计划确认权限，商户已经完成服务入驻，请保障调用此接口的服务和对应待签约的支付分计划创建时的服务一致
2. 请保障支付分计划ID对应计划状态为NORMAL
3. 请保障传入的OpenID或sub_openid对应的用户是待签约的用户
4. notify_url字段传入的URL用于接收后续签约成功的通知和该签约计划用户主动取消的通知
5. sign_plan_detail字段根据创建支付分计划时传入的计划详情数量和顺序传入对应计划详情后续使用时（既创建对应支付分服务订单时）的商户侧单号，请保证唯一
6. 创建用户的签约计划成功后会返回package字段用于作为拉起支付分签约页的参数

步骤3 拉起支付分签约页，让用户进行计划签约 我们通过以下前端方法可调起微信客户端（注意区分场景），用户在调起页面中完成支付分计划的签约

• App调起支付分-签约计划
• JSAPI调起支付分-签约计划
• 小程序调起支付分-签约计划

发起支付分计划用户签约后，我们需要确认用户签约是否成功，共有两种方法：

• 签约成功后会根据创建用户签约计划中的notify_url参数发起签约成功回调——签约成功回调通知API
• 通过接口主动查询(未及时收到用户签约成功通知情况下且用户已回到商家授权页面时商户侧主动查询。)——查询用户的签约计划

用户签约计划后，如果主动取消已签约的计划，会根据创建用户签约计划中的notify_url参数发起取消签约的回调——取消签约回调通知API

步骤4 在用户使用已签约计划内指定计划详情对应服务时，创建已签约计划待使用计划详情对应的服务订单 调用创建用户的签约计划详情对应的服务订单接口创建已签约计划待使用计划详情对应的服务订单

1. 调用接口时请确保传入的服务ID有效，对应服务已经开通了支付分按计划确认权限，商户已经完成服务入驻，请保障调用此接口的服务和对应创建用户的签约计划时的服务一致
2. 调用接口时请确保传入的签约计划ID所对应计划的状态有效，可以通过查询用户的签约计划接口查询指定用户的签约计划
3. 创建已签约计划待使用计划详情对应的服务订单时，请确保待创建订单的计划详情前置计划详情已经取消或者已完结且用户支付成功，可以通过查询用户的签约计划接口查询指定用户的签约计划详情信息
4. 创建已签约计划待使用计划详情对应的服务订单时，请确保待创建订单传入的商户侧单号out_trade_no和创建用户的签约计划时所传的计划详情对应的商户侧单号一致

步骤5 商户为用户提供服务，待服务结束后，商户调用完结订单接口完结当前订单 调用完结支付分订单API接口后，微信支付分就会发起对用户的扣款，但是在用户扣款过程中可能会出现一些特殊情况，下面列举了几种特殊情况以及对应的处理方法，供大家参考：

• 扣款过程中，用户通过其它方式完成了支付，希望微信支付分停止继续扣款

  处理方法：商户调用同步服务订单信息接口将订单支付成功状态同步给微信支付分，微信支付分将停止继续扣款的操作

• 用户中途取消服务，不继续进行

  处理方法：商户调用取消支付分服务订单接口，订单取消后对应计划详情也会对应取消

步骤6 收到用户扣款成功通知，业务流程结束

通过支付成功回调通知API接口可以获取到用户扣款成功的通知，同时，商户也可以根据情况通过查询支付分订单API接口主动查询扣款情况。

• 如订单状态state=DONE，且收款状态collection.state=USER_PAID，代表扣款成功
• 如订单状态state=DOING，state_description=MCH_COMPLETE，且收款状态collection.state=USER_PAYING，代表扣款进行中

如遇到网络、服务器等原因造成无法正常接收扣款成功通知，一般有两种解决方法：

1. 主动查单，通过查询支付分订单API (opens new window) 接口主动查询扣款情况
2. 次日对账，通过申请交易账单API (opens new window)接口申请交易账单，再通过后台接口下载账单API (opens new window)下载交易账单

3.2. API接入（含示例代码）

本文档展示了如何使用微信支付服务端 SDK 快速接入微信支付分产品，完成与微信支付对接的部分。

注意

• 文档中的代码示例是用来阐述 API 基本使用方法，代码中的示例参数需替换成商户自己账号及请求参数才能跑通。
• 以下接入步骤仅提供参考，请商户结合自身业务需求进行评估、修改。

3.2.1. 【服务端】创建支付分计划

步骤说明： 商户创建一个支付分计划，该计划包含了一组为用户提供的服务，方便商家让用户在一次性对整个计划的所有扣费内容完成确认。

示例代码

重要入参说明：

1. 调用接口时请确保传入的服务ID{service_id}有效，对应服务已经开通了支付分按计划确认权限，商户已经完成服务入驻
2. 支付分计划有效期(单位天){plan_duration}和支付分计划扣费次数{deduction_quantity}确保小于等于服务规定的最大支付分计划有效期(单位天)和支付分计划扣费次数
3. 支付分计划明细列表{plan_detail_list}中计划明细数量确保等于支付分计划扣费次数{deduction_quantity}
4. 支付分系统会根据支付分计划明细列表中的计划明细顺序给计划明细按顺序从1开始编号，每个计划明细请确保计划明细原支付金额(单位分){original_price}大于等于计划明细实际支付金额(单位分){actual_price}，且每个计划明细的计划明细实际支付金额(单位分){actual_price}需要小于等于按顺序的上一个计划明细

更多参数、响应详情及错误码请参见创建支付分计划接口文档。

3.2.2. 【服务端】查询支付分计划

步骤说明： 可以通过查询支付分计划接口确认支付分计划状态和具体信息。

示例代码

重要入参说明：

• 查询条件参数merchant_plan_no是在接口URL中传递的，请勿传到body中去。

更多参数、响应详情及错误码请参见查询支付计划接口文档。

3.2.3. 【服务端】停止支付分计划

步骤说明： 商户不希望计划继续签约时，可以调用停止支付分计划接口，计划停止后无法继续签约，已签约的计划可以继续完成服务，既创建计划详情对应的支付分服务订单。

示例代码

重要入参说明：

1. 条件参数merchant_plan_no是在接口URL中传递的，请勿传到body中去。

更多参数、响应详情及错误码请参见停止支付分计划接口文档。

3.2.4. 【服务端】创建用户的签约计划

步骤说明： 用户在商户侧下单购买计划时，商户发起支付分计划用户签约，此时首先我们需要创建一个支付分用户的签约计划以提供给用户进行签约。

示例代码

重要入参说明：

1. 调用接口时请确保传入的服务ID{service_id}有效，对应服务已经开通了支付分按计划确认权限，商户已经完成服务入驻，请保障调用此接口的服务和对应待签约的支付分计划创建时的服务一致
2. 请保障传入的OpenID或sub_openid对应的用户是待签约的用户,且只能传其中之一，在使用sub_openid标记用户时，sub_appid必传
3. sign_plan_detail字段根据创建支付分计划时传入的计划详情数量和顺序传入对应计划详情后续使用时（既创建对应支付分服务订单时）的商户侧单号{merchant_plan_detail_no}，请保证唯一

更多参数、响应详情及错误码请参见创建支付分用户的签约计划接口文档。

3.2.5. 【客户端】跳转签约计划页

微信支付根据用户不同的使用场景（App、小程序、微信内H5）分别提供了对应跳转签约计划页的方法，请根据场景进行选择，详见：

• App调起支付分-签约计划 (opens new window)
• JSAPI调起支付分-签约计划 (opens new window)
• 小程序调起支付分-签约计划 (opens new window)

3.2.6. 【服务端】签约计划成功通知

步骤说明： 当用户完成计划签约时，微信会把相关信息异步回调的方式通知商户，商户需要接收处理，并按文档规范返回应答

注意

• 支付结果通知是以POST 方法访问商户设置的通知URL，通知的数据以JSON 格式通过请求主体（BODY）传输。通知的数据包括了加密的支付结果详情
• 加密不能保证通知请求来自微信。微信会对发送给商户的通知进行签名，并将签名值放在通知的HTTP头Wechatpay-Signature。商户应当验证签名，以确认请求来自微信，而不是其他的第三方。签名验证的算法请参考 《微信支付API v3签名验证》。
• 支付通知HTTP应答码为200或204才会当作正常接收，当回调处理异常时，应答的HTTP状态码应为500，或者4xx
• 商户成功接收到回调通知后应返回成功的HTTP应答码为200或204
• 同样的通知可能会多次发送给商户系统。商户系统必须能够正确处理重复的通知。 推荐的做法是，当商户系统收到通知进行处理时，先检查对应业务数据的状态，并判断该通知是否已经处理。如果未处理，则再进行处理；如果已处理，则直接返回结果成功。在对业务数据进行状态检查和处理之前，要采用数据锁进行并发控制，以避免函数重入造成的数据混乱。

更多参数、响应详情及错误码请参见签约成功回调通知API接口文档

3.2.7. 【服务端】查询用户的签约计划

步骤说明： 可以通过查询用户的签约计划接口确认用户签约计划的信息。

示例代码

重要入参说明：

• 查询条件参数merchant_sign_plan_no是在接口URL中传递的，请勿传到body中去。

更多参数、响应详情及错误码请参见查询用户的签约计划接口文档。

3.2.8. 【服务端】取消用户的签约计划

步骤说明： 商户想要终止用户签约计划后续计划详情的服务，可以调用取消用户的签约计划接口，签约计划被取消后，剩余未使用的计划详情将无法提供服务，既创建对应的服务订单，已经创建了服务订单的计划详情不受影响可以正常完结、取消。

示例代码

重要入参说明：

1. 条件参数merchant_sign_plan_no是在接口URL中传递的，请勿传到body中去。

更多参数、响应详情及错误码请参见取消用户的签约计划接口文档。

3.2.9. 【服务端】创建用户的签约计划详情对应的服务订单

步骤说明： 在用户使用已签约计划内指定计划详情对应服务时，创建已签约计划待使用计划详情对应的服务订单。

示例代码

重要入参说明：

1. 调用接口时请确保传入的服务ID{service_id}有效，对应服务已经开通了支付分按计划确认权限，商户已经完成服务入驻，请保障调用此接口的服务和对应创建用户的签约计划时的服务一致
2. 创建已签约计划待使用计划详情对应的服务订单时，请确保待创建订单的计划详情前置计划详情已经取消或者完成使用且用户支付成功
3. 创建已签约计划待使用计划详情对应的服务订单时，请确保待创建订单传入的商户侧单号out_trade_no和创建用户的签约计划时所传的计划详情对应的商户侧单号一致

更多参数、响应详情及错误码请参见创建用户的签约计划详情对应的服务订单接口文档。

3.2.10. 【服务端】完结支付分订单

步骤说明： 用户服务结束后，商户通过请求完结支付分订单接口，通过微信支付分进行用户扣款操作。

示例代码

更多参数、响应详情及错误码请参见 完结支付分订单API接口文档。

3.2.11. 【服务端】取消支付分订单

步骤说明： 订单为以下状态时可以取消订单：CREATED（已创单）、DOING（进行中）（包括商户完结支付分订单后，且支付分订单收款状态为待支付USER_PAYING）。

示例代码

更多参数、响应详情及错误码请参见取消支付分订单API接口文档。

3.2.12. 【服务端】查询支付分订单

步骤说明： 一般在创建订单后、订单完结成功后等关键流程中，商户可能有知晓订单状态的需求，此时即可通过该接口查询订单状态。

示例代码

更多参数、响应详情及错误码请参见 查询支付分订单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. 【服务端】申请交易账单

步骤说明： 微信支付按天提供交易账单文件，商户可以通过该接口获取账单文件的下载地址。

示例代码

更多参数、响应详情及错误码请参见 申请交易账单API (opens new window)接口文档。

3.2.15. 【服务端】下载交易账单

步骤说明： 通过申请交易账单接口获取到账单下载地址（download_url）后，再通过该接口获取到对应的账单文件，文件内包含交易相关的金额、时间、营销等信息，供商户核对订单、退款、银行到账等情况

示例代码

注意

• 账单文件的下载地址的有效时间为30s
• 强烈建议商户将实际账单文件的哈希值和之前从接口获取到的哈希值进行比对，以确认数据的完整性

更多参数、响应详情及错误码请参见 下载账单API接口文档。