支付中签约api

1. 应用场景

支付的同时完成代扣协议的签约。

2. 开发流程介绍

第一步 : 请求支付中签约接口(接口请求参数见下文),获取预支付id (对应参数:prepay_id). 此步骤需要根据不同支付方式选择不同的trade_type(trade_type详细介绍请参见交易类型规则).

第二步 : 按照不同支付方式的不同规则,按要求唤起微信支付收银台.不同的支付方式,对于唤起微信支付收银台的方法要求不同,具体可以参见以下表格:

扫码支付(NATIVE)详见: 扫码支付(NATIVE)在线文档
公众号支付(JSAPI)详见: 公众号支付(JSAPI)在线文档
App支付(APP)详见: App支付(APP)在线文档
H5(MWEB)支付详见: H5(MWEB)在线文档
小程序(JSAPI)支付详见: 小程序支付在线文档

第三步 : 用户完成支付,微信通过支付中签约接口中商户上传的通知回调地址(对应参数:notify_url),将支付结果返回给商户,同时将签约结果通过contract_notify_url通知给商户,两次通知皆为异步通知.

3. 支付中签约接口

请求Url https://api.mch.weixin.qq.com/pay/contractorder
是否需要证书
请求方式 POST

请求参数

字段名 字段 必填 类型 示例值 说明
请求appid appid String(32) wxcbda96de0b165486 appid是商户在微信申请公众号或移动应用成功后分配的帐号ID,登录平台为mp.weixin.qq.com或open.weixin.qq.com
商户号 mch_id String(32) 1200009811 商户号是商户在微信申请微信支付成功后分配的帐号ID,登录平台为pay.weixin.qq.com
签约商户号 contract_mchid String(32) 1200009811 签约商户号,必须与mch_id一致
签约appid contract_appid String(32) wxcbda96de0b165486 签约公众号,必须与appid一致
商户订单号 out_trade_no String(32) 123456 商户系统内部的订单号,32个字符内、可包含字母, 其他说明见商户订单号
设备号 device_info String(32) 013467007045764 终端设备号(门店号或收银设备ID),注意:PC网页或公众号内支付请传"WEB"
随机字符串 nonce_str string(32) 5K8264ILTKCH16CQ2502SI8ZNMTM67VS 随机字符串,不长于32位.
商品描述 body String(128) Ipad mini 16G 白色 商品或支付单简要描述
商品详情 detail String(8192) Ipad mini 16G 白色 商品名称明细列表
附加数据 attach String(127) 深圳分店 附加数据,在查询API和支付通知中原样返回,该字段主要用于商户携带订单的自定义数据
回调通知ur notify_url String(32) http://yoursite.com 回调通知的url
总金额 total_fee Int 888 订单总金额,单位为分
终端IP spbill_create_ip String(16) 123.12.12.123 APP和网页支付提交用户端ip,Native支付填调用微信支付API的机器IP.
交易起始时间 time_start String(14) 20091225091010 订单生成时间,格式为yyyyMMddHHmmss,如2009年12月25日9点10分10秒表示为20091225091010. 其他详见时间规则
交易结束时间 time_expire String(14) 20091227091010 订单失效时间,格式为yyyyMMddHHmmss,如2009年12月27日9点10分10秒表示为20091227091010. 其他详见时间规则 注意:最短失效时间间隔必须大于5分钟
商品标记 goods_tag String(32) WXG 商品标记,代金券或立减优惠功能的参数
交易类型 trade_type String(16) JSAPI 取值如下:JSAPI,NATIVE,APP,MWEB
商品ID product_id String(32) 12235413214070356458058 trade_type=NATIVE,此参数必传. 此id为二维码中包含的商品ID,商户自行定义.
指定支付方式 limit_pay String(32) no_credit no_credit--指定不能使用信用卡支付
用户标识 openid String(128) oUpF8uMuAJO_M2pxb1Q9zNjWeS6o trade_type=JSAPI,此参数必传,用户在商户appid下的唯一标识.
模板id plan_id int 123 协议模板id
签约协议号 contract_code String(32) 100001256 签约协议号
请求序列号 request_serial Int64 1695 商户请求签约时的序列号,要求唯一性。序列号主要用于排序,不作为查询条件,纯数字,范围不能超过Int64的范围(9223372036854775807)。
用户账户展示名称 contract_display_account String 123 签约用户的名称,用于页面展示,参数值不支持UTF8非3字节编码的字符,例如表情符号,所以请勿传微信昵称到该字段
签约信息通知url contract_notify_url String http://yoursite.com 签约信息回调通知的url
签名 sign String(32) E1EE61A91C8E90F299DE6AE075D60A2D 签名规则详见签名生成算法 注:所有参数都是encode前做签名

5. 返回参数

字段名 变量名 必填 类型 示例值 说明

返回状态码

return_code

String(16)

SUCCESS

SUCCESS/FAIL
此字段是通信标识,非交易标识,交易是否成功需要查看result_code来判断.

返回信息

return_msg

String(128)

签名失败

返回信息,如非空,为错误原因
签名失败
参数格式校验错误

以下字段在return_code为SUCCESS的时候返回

业务结果

result_code

String(16)

SUCCESS

SUCCESS/FAIL

请求appid appid String(32) wxcbda96de0b165486 appid是商户在微信申请公众号或移动应用成功后分配的帐号ID,登录平台为mp.weixin.qq.com或open.weixin.qq.com
商户号 mch_id String(32) 1200009811 商户号是商户在微信申请微信支付成功后分配的帐号ID,登录平台为pay.weixin.qq.com

随机字符串

nonce_str

String(32)

5K8264ILTKCH16CQ2502SI8ZNMTM67VS

随机字符串,不长于32位.

签名

sign

String(32)

E1EE61A91C8E90F299DE6AE075D60A2D

签名规则详见签名生成算法 注:所有参数都是encode前做签名.

错误代码

err_code

String(32)

SYSTEMERROR

错误返回的错误代码

错误代码描述

err_code_des

String(128)

系统错误

错误返回的信息描述

预签约结果

contract_result_code

String

SUCCESS

预签约结果

预签约错误代码

contract_err_code

String

Fail

预签约错误代码

预签约错误描述

contract_err_code_des

String

已签约

预签约错误描述

以下字段在return_code 和result_code都为SUCCESS的时候有返回

签名

sign

String(32)

C380BEC2BFD727A4B6845133519F3AD6

详见签名生成算法

公众账号id

appid

String(32)

wxcbda96de0b165486

微信支付分配的公众账号id

商户号

mch_id

String(32)

10000098

微信支付分配的商户号

预支付交易会话标识

prepay_id

String(64)

wx201410272009395522657a690389285100

微信生成的预支付回话标识,用于后续接口调用中使用,该值有效期为2小时.

交易类型

trade_type

String(16)

JSAPI

调用接口提交的交易类型,取值如下:JSAPI,NATIVE,APP

二维码链接

code_url

String(64)

weixin://wxpay/s/An4baqw

trade_type为NATIVE是有返回,可将该参数值生成二维码展示出来进行扫码支付

模板id

plan_id

Int

123

商户在微信商户平台设置的代扣协议模板id

请求序列号

request_serial

Uint64

1695

商户请求签约时的序列号,商户侧须唯一

签约协议号

contract_code

String

1023658866

商户请求签约时传入的签约协议号,商户侧须唯一

用户账户展示名称

contract_display_account

String

张三

签约用户的名称,用于页面展示

支付跳转链接 mweb_url String(64) https://wx.tenpay.com/cgi-bin/mmpayweb-bin/checkmweb?prepay_id=wx2016121516420242444321ca0631331346&package=1405458241 mweb_url为拉起微信支付收银台的中间页面,可通过访问该url来拉起微信客户端,完成支付,mweb_url的有效期为5分钟。

商户订单号

out_trade_no

String(32)

123456

商户订单号

6. 错误码

错误码 描述 解决方案

SIGN_ERROR

签名错误

验证签名算法

PARAMETER FAIL

参数错误

验证参数

XML FAIL

XML格式错误

检查XML格式

RESULT NULL

查询为空

传入正确查询参数

MERCHANT PERMISSION ERROR

受理商户没有权限

确认商户权限

INVALID PLAN_ID

签约模板无效

检查正确模板id

CONTRACT_CODE DUPLICATION

该签约号已存在

contract_code已经被签约,请传入不重复的签约号

MERCHANT AUTHORITY ERROR

商户权限校验失败

联系相关接口人确认委托代扣权限