创建用户的签约计划

更新时间：2024.09.02

商户通过此接口基于商户已创建且正常进行中的支付分计划，创建用户的签约计划以供用户签约

接口说明

支持商户：【普通商户】

请求方式：【POST】/v3/payscore/sign-plan/user-sign-plans

请求域名：【主域名】https://api.mch.weixin.qq.com 使用该域名将访问就近的接入点

　　　　　【备域名】https://api2.mch.weixin.qq.com 使用该域名将访问异地的接入点，指引点击查看

请求参数

Header HTTP头参数

Authorization 　必填　string

请参考签名认证生成认证信息

Accept 　必填　string

请设置为application/json

Content-Type 　必填　string

请设置为application/json

body 包体参数

service_id 　必填 string(32)

【支付分服务ID】创建的签约计划所属计划必须是该服务ID下的计划

plan_id 　必填 string(32)

【支付分计划ID】由本商户创建的，待用户签约的支付分计划ID

appid 　必填 string(32)

【AppID】AppID

openid 　必填 string(128)

【待签约用户在商户应用下的OpenID】待签约用户在商户应用下的OpenID

merchant_sign_plan_no 　必填 string(32)

【商户签约计划单号】商户系统内部签约计划单号，只能是数字、大小写字母_-* 且在同一个商户号下唯一

notify_url 　必填 string(1024)

【签约成功事件通知回调地址】签约成功事件通知回调地址，用于接收用户签约计划成功后的通知

sign_plan_detail 　必填 array[UserSignPlanDetailMerchatNo]

【签约计划对应的计划详情列表的商户侧单号信息】上传用户签约的计划对应各个详情在使用（创建支付分订单）时的商户侧订单号，计划明细序号对应创建支付分计划时的计划明细序号

属性

请求示例

1curl -X POST \
2  https://api.mch.weixin.qq.com/v3/payscore/sign-plan/user-sign-plans \
3  -H "Authorization: WECHATPAY2-SHA256-RSA2048 mchid=\"1900000001\",..." \
4  -H "Accept: application/json" \
5  -H "Content-Type: application/json" \
6  -d '{
7    "service_id" : "2002000000000558128851361561536",
8    "plan_id" : "01000033210000324638000000376258",
9    "appid" : "wxd678efh567hg6787",
10    "openid" : "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o",
11    "merchant_sign_plan_no" : "1234323JKHDFE1243252",
12    "notify_url" : "https://api.test.com",
13    "sign_plan_detail" : [
14      {
15        "plan_detail_no" : 1,
16        "merchant_plan_detail_no" : "1234323JKHDFE1243252"
17      }
18    ]
19  }'
20

应答参数

200 OK

sign_plan 　必填 object

【用户的签约计划】待用户的签约计划

属性

sign_plan_id 　必填 string(32)

【计划签约ID】签约计划的主键，唯一定义此资源的标识

openid 　选填 string(128)

【签约计划用户应用下的OpenID】签约计划用户应用下的OpenID

service_id 　必填 string(32)

【计划所属服务】计划所属服务

mchid 　必填 string(32)

【商户号】商户号

appid 　必填 string(32)

【AppID】AppID

merchant_sign_plan_no 　必填 string(32)

【商户侧签约计划号】商户侧签约计划号

merchant_callback_url 　必填 string(1024)

【商户回调地址】商户回调地址

plan_id 　必填 string(32)

【签约所属计划ID】签约所属计划ID

going_detail_no 　必填 integer

【目前用户进行到的计划详情序号】序号从1开始，顺序按照创建计划时传入的计划详情顺序，0代表无任何详情开始使用

sign_state 　必填 string

【计划签约状态】计划签约状态

可选取值：

UNSIGNED: 用户未签约

SIGNED: 用户已签约

SIGN_PLAN_CANCEL: 签约计划已取消

COMPLETE: 签约计划的所有计划详情已经全部完成

EXPIRE: 签约计划已过期

cancel_sign_time 　选填 string(32)

【签约计划取消时间】使用 rfc3339 所定义的 date-time 格式，使用北京时间（+08:00），格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC8小时，即北京时间）。例如：2023-09-06T19:29:58+08:00表示，北京时间2023年9月6日 19点29分58秒。

cancel_sign_type 　选填 string

【签约计划取消类型】签约计划取消类型

可选取值：

NOT_CANCEL: 用户已签约协议未取消

USER: 用户取消已签约的协议

MERCHANT: 商户取消已签约的协议

REVOKE_SERVICE: 用户解除服务授权时取消服务下的已签约协议

cancel_reason 　选填 string(128)

【签约计划取消原因】签约计划取消原因

plan_name 　必填 string(20)

【签约计划的名称】签约计划的名称

plan_over_time 　必填 string(32)

【签约计划的过期时间】使用 rfc3339 所定义的 date-time 格式，使用北京时间（+08:00），格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC8小时，即北京时间）。例如：2023-09-06T19:29:58+08:00表示，北京时间2023年9月6日 19点29分58秒。

total_origin_price 　必填 integer

【签约计划原总金额(单位分)】签约计划原总金额(单位分)

deduction_quantity 　必填 integer

【签约计划扣费次数】签约计划扣费次数

total_actual_price 　必填 integer

【签约计划实际总金额（单位分）】签约计划实际总金额（单位分）

signed_detail_list 　选填 array[object]

【签约计划明细列表】签约计划明细列表

属性

plan_detail_no 　必填 integer

【计划明细序号】根据创建计划时传入明细顺序编号，从1开始

original_price 　必填 integer

【计划明细原支付金额（单位分）】计划明细原支付金额（单位分）

plan_discount_description 　选填 string(20)

【计划明细优惠说明】计划明细优惠说明

actual_price 　必填 integer

【计划明细实际支付金额（单位分）】计划明细实际支付金额（单位分）

plan_detail_state 　必填 string

【计划明细状态】计划明细状态

可选取值：

NOT_USED: 本计划详情还未使用

USING: 本计划详情使用中，已有对应的服务订单

USED: 本计划详情已使用，对应的服务订单已完成支付

SIGN_PLAN_DETAIL_CANCEL: 本计划详情已取消使用，对应的服务订单已取消

order_id 　选填 string(32)

【计划明细对应的支付分服务单号】计划明细在使用中，已使用和已取消状态下存在对应的支付分服务订单号

merchant_plan_detail_no 　必填 string(32)

【商户侧计划明细使用订单号】必须保障在商户下唯一，会在创建计划详情对应的支付分订单时会使用该字段作为支付分订单商户侧订单号,只能是数字、大小写字母_-*

plan_detail_name 　必填 string(20)

【计划详情名称】计划详情名称

actual_pay_price 　选填 integer

【计划明细对应订单实际支付金额（单位分）】单位分，计划明细对应订单实际支付金额，是根据完结订单填写金额，订单完结后用户实际支付此金额

use_time 　选填 string(32)

【详情使用时间】详情使用后回传，使用 rfc3339 所定义的 date-time 格式，使用北京时间（+08:00），格式为yyyy-MM-DDTHH:mm:ss:sss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss:sss表示时分秒毫秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC8小时，即北京时间）。例如：2021-05-20T13:29:35:120+08:00表示，北京时间2021年5月20日 13点29分35秒120毫秒。

complete_time 　选填 string(32)

【详情完成时间】详情对应订单实际完成支付时间，使用 rfc3339 所定义的 date-time 格式，使用北京时间（+08:00），格式为yyyy-MM-DDTHH:mm:ss:sss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss:sss表示时分秒毫秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC8小时，即北京时间）。例如：2021-05-20T13:29:35:120+08:00表示，北京时间2021年5月20日 13点29分35秒120毫秒。

cancel_time 　选填 string(32)

【详情取消时间】详情对应订单取消时间，使用 rfc3339 所定义的 date-time 格式，使用北京时间（+08:00），格式为yyyy-MM-DDTHH:mm:ss:sss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss:sss表示时分秒毫秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC8小时，即北京时间）。例如：2021-05-20T13:29:35:120+08:00表示，北京时间2021年5月20日 13点29分35秒120毫秒。

sign_time 　选填 string(32)

【签约时间】使用 rfc3339 所定义的 date-time 格式，使用北京时间（+08:00），格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC8小时，即北京时间）。例如：2023-09-06T19:29:58+08:00表示，北京时间2023年9月6日 19点29分58秒。

package 　必填 string

【跳转微信侧确认签约小程序的数据】跳转微信侧确认签约小程序的数据，创建用户的签约计划成功后，作为拉起用户签约页的参数，需要先URLEncode后传入

应答示例

200 OK

1{
2  "sign_plan" : {
3    "sign_plan_id" : "01010033210001424338000019876258",
4    "openid" : "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o",
5    "service_id" : "2002000000000558128851361561536",
6    "mchid" : "1900000109",
7    "appid" : "wxd678efh567hg6787",
8    "merchant_sign_plan_no" : "1234323JKHDFE1243252",
9    "merchant_callback_url" : "https://api.test.com",
10    "plan_id" : "01000033210000324638000000376258",
11    "going_detail_no" : 2,
12    "sign_state" : "UNSIGNED",
13    "cancel_sign_time" : "2021-05-20T13:29:35.120+08:00",
14    "cancel_sign_type" : "NOT_CANCEL",
15    "cancel_reason" : "用户放弃课程",
16    "plan_name" : "瑜伽晨练课10次",
17    "plan_over_time" : "2021-05-20T13:29:35.120+08:00",
18    "total_origin_price" : 150000,
19    "deduction_quantity" : 10,
20    "total_actual_price" : 120000,
21    "signed_detail_list" : [
22      {
23        "plan_detail_no" : 1,
24        "original_price" : 30000,
25        "plan_discount_description" : "享9折优惠",
26        "actual_price" : 27000,
27        "plan_detail_state" : "NOT_USED",
28        "order_id" : "0000300001201908301055157220022",
29        "merchant_plan_detail_no" : "1234323JKHDFE1243252",
30        "plan_detail_name" : "第一节课",
31        "actual_pay_price" : 50000,
32        "use_time" : "2021-05-20T13:29:35.120+08:00",
33        "complete_time" : "2021-05-20T13:29:35.120+08:00",
34        "cancel_time" : "2021-05-20T13:29:35.120+08:00"
35      }
36    ],
37    "sign_time" : "2021-05-20T13:29:35.120+08:00"
38  },
39  "package" : "Easdfowealsdkjfnlaksjdlfkwqoi&wl3l2sald"
40}
41

错误码

公共错误码

状态码	错误码	描述	解决方案
400	PARAM_ERROR	参数错误	请根据错误提示正确传入参数
400	INVALID_REQUEST	HTTP 请求不符合微信支付 APIv3 接口规则	请参阅接口规则
401	SIGN_ERROR	验证不通过	请参阅签名常见问题
500	SYSTEM_ERROR	系统异常，请稍后重试	请稍后重试

业务错误码

状态码	错误码	描述	解决方案
400	INVALID_REQUEST	计划扣费次数和计划明细条数不一致	请确认待创建的支付分计划填写的扣费次数和计划详情数量是否一致
400	INVALID_REQUEST	前一笔实际扣费金额需大于等于后一笔实际扣费金额	请确认每一个计划明细的实际扣费金额必须小于等于上一个计划明细的实际扣费金额
400	PARAM_ERROR	计划明细中每一笔原扣费金额需要大于等于实际扣费金额	请确认每一个计划详情中的实际扣费金额必须小于等于本计划详情中的原扣费金额
400	INVALID_REQUEST	计划扣费金额和计划明细中扣费金额之和不一致	请核对计划的实际扣费总金额和每一个计划明细的实际扣费金和相同
400	INVALID_REQUEST	计划原扣费金额和计划明细中原扣费金额之和不一致	请核对计划的原扣费总金额和每一个计划明细的原扣费金和相同
400	PARAM_ERROR	总实付金额不能为0	请检查待创建的计划的总实付金额和原金额必须大于0
400	INVALID_REQUEST	无效的AppID,请检查AppID是否正确	检查填写的AppID是否合法
400	INVALID_REQUEST	商户和AppID未绑定	检查传入的AppID和调用API的商户是否有绑定关系
400	INVALID_REQUEST	商户暂无权限使用此服务	请检查调用方商户是否入驻了支付分服务
400	INVALID_REQUEST	此服务无按计划确认权限	请检查传入的支付分服务是否开通按计划确认权限
400	INVALID_REQUEST	实付金额必须小于最大风险金	请检查每一个计划明细的实付金额是否小于等于支付分服务规定的最大风险金
400	INVALID_REQUEST	计划的最长持续时间不能超过服务规定的计划最长时间	请检查待创建支付分计划的有效期是否小于等于服务规定的计划最长持续时间
400	INVALID_REQUEST	计划的最大扣费次数不能超过服务规定的最大扣费次数	请检查待创建支付分计划的扣费次数是否小于等于服务规定的最大扣费次数
400	INVALID_REQUEST	支付分计划单号已被使用,请检查	该商户侧计划号已经创建了对应支付分计划，且本次请求参数和已创建计划不一致，如需创建新的支付分计划请更换商户侧计划号重试
400	PARAM_ERROR	签约计划详情序号不能重复	请核对签约计划对应的计划详情列表的商户侧单号信息中每一个计划明细序号不重复
400	PARAM_ERROR	商户侧计划明细使用订单号不能重复	请核对签约计划对应的计划详情列表的商户侧单号信息中每一个计划明细序号对应的商户侧计划明细使用订单号不重复
400	INVALID_REQUEST	发起签约的计划不存在	请检查传入的支付分计划号，或先创建一个支付分计划
403	NOAUTH	商户只能发起自身创建计划的签约	请检查待签约的计划创建商户是否是本次发起签约的商户
403	NOAUTH	服务ID和待签约计划所属服务ID不一致	请检查待签约的计划创建时的支付分服务和本次发起签约的支付分服务是否一致
400	INVALID_REQUEST	当前计划状态无法发起签约	请检查发起签约的计划状态是否为NORMAL
400	INVALID_REQUEST	发起签约时填写的计划详情数量和计划不一致	请检查签约计划对应的计划详情列表数量和待签约计划详情数量是否一致，确保每一个计划明细都有对应的商户侧计划明细使用订单号
400	INVALID_ORDER_STATE	单据状态错误	确认操作是否符合流程
400	INVALID_REQUEST	请求参数符合参数格式，但不符合业务规则	请确认相同单号是否使用了不同的参数
400	ORDER_CANCELED	单据已取消	当前状态无需操作
400	ORDER_DONE	订单已完成	当前状态无需操作
429	FREQUENCY_LIMITED	频率超限	请求量不要超过接口调用频率限制

文档是否有帮助

更多支持

开发文档(服务商)开发文档(V2版)开发者社区微信开放平台微信公众平台腾讯客服