申请签约

应用场景

商户可以通过请求此接口唤起微信委托代扣的页面,页面样例见案例与规范

用户在微信的页面中完成代扣签约后,微信会同时将签约信息通过异步通知的方式通知给商户后台。如果用户放弃签约或签约失败则不通知。

接口调用请求说明

请求Url https://api.mch.weixin.qq.com/papay/entrustweb
是否需要证书
请求方式 GET
注:如果请求来源是商户APP,则必须使用最新的微信支付sdk,并开通权限。微信代扣SDK下载 APP跳转签约页面方法指引

请求参数

字段名 字段 必填 类型 示例值 说明
请求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
模板id plan_id String(28) 12535 协议模板id,设置路径见开发步骤
签约协议号 contract_code String(32) 100000 商户侧的签约协议号,由商户生成
请求序列号 request_serial Int64 1000 商户请求签约时的序列号,要求唯一性。序列号主要用于排序,不作为查询条件,纯数字,范围不能超过Int64的范围(9223372036854775807)。
用户账户展示名称 contract_display_account String(32) 微信代扣 签约用户的名称,用于页面展示,,参数值不支持UTF8非3字节编码的字符,例如表情符号,所以请勿传微信昵称到该字段
回调通知url notify_url String https://weixin.qq.com 用于接收签约成功消息的回调通知地址,以http或https开头。请对notify_url参数值进行encode处理。当签约场景为APP时,且系统为ios时,需要对参数值做两次encode。
版本号 version string 1.0 固定值1.0

签名

sign

String(32)

C380BEC2BFD727A4B6845133519F3AD6

详见签名生成算法
时间戳 timestamp String(10) 1414488825 系统当前时间,10位

以下字段为非必填项,用来控制签约页面结束后的返回路径(不传此参数,则签约完成后停留在微信内),规则如下:

1- 默认返回模式为关闭当前页面

2- 优先级: return_app>return_web

3- 下面参数不传或无效则默认关闭当前页面

返回app

return_app

Int

3

3表示返回app, 不填则不返回 注:签约参数appid必须为发起签约的app所有,且在微信开放平台注册过。

返回web

return_web

Int

1

1表示返回签约页面的referrer url, 不填或获取不到referrer则不返回; 跳转referrer url时会自动带上参数from_wxpay=1

return_app方法具体说明:

// 微信发送请求到第三方应用时,会回调到以下方法
 public void onReq(BaseReq req) {
  Intent intent = new Intent( WXEntryActivity.this, OnlineDirectOrderActivity.class );
  intent.setFlags( Intent.FLAG_ACTIVITY_NEW_TASK );
  startActivity( intent );
  finish();
 }
具体的原理可以搜索下FLAG_ACTIVITY_NEW_TASK这个flag的行为

返回值from=weixin_papay
BaseReq req =  {
  "country": "CN",
  "lang": "zh_CN",
  "message": {
    "mediaObject": {
      "extInfo": "from=weixin_papay"
    },
    "messageExt": "from=weixin_papay",
    "sdkVer": 620823808,
    "type": 7
  },
  "openId": "oDgvFjh76JB7iVqPFD_YGaC7QK6Y",
  "transaction": "771deb9f301efbaaac9216d46fbf894c",
  "type": 4
}

签约请求数据示例:notify_url的内容部分需做一次encode,app场景下,如果是ios环境,notify_url需做两次encode。

https://api.mch.weixin.qq.com/papay/entrustweb?appid=wx426a3015555a46be&contract_code=122&contract_display_account=name1&mch_id=1223816102&notify_url=www.qq.com%2Ftest%2Fpapay&plan_id=106&request_serial=123&timestamp=1414488825&version=1.0&sign=FF1A406564EE701064450CA2149E2514

返回参数(异步返回)

签约成功后,微信会把相关签约结果异步发送给商户,返回的url为调用上述签约接口时填写的notify_url字段。商户在收到签约结果通知后,需进行接收处理并返回应答
对后台通知交互时,如果微信收到商户的应答不是成功或超时,微信认为通知失败,微信会通过一定的策略定期重新发起通知,尽可能提高通知的成功率,但微信不保证通知最终能成功。
(通知频率为15/15/30/180/1800/1800/1800/1800/3600,单位:秒)
由于存在重新发送后台通知的情况,因此同样的通知可能会多次发送给商户系统。商户系统必须能够正确处理重复的通知。
推荐的做法是,当收到通知进行处理时,首先检查对应业务数据的状态,判断该通知是否已经处理过,如果没有处理过再进行处理,如果处理过直接返回结果成功。在对业务数据进行状态检查和处理之前,要采用数据锁进行并发控制,以避免函数重入造成的数据混乱。

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

返回状态码

return_code

SUCCESS

String(16)

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

返回信息

return_msg

签名失败

String(128)

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

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

业务结果

result_code

SUCCESS

String(16)

SUCCESS/FAIL

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

商户号

mch_id

10000098

String(32)

微信支付分配的商户号

签约协议号

contract_code

100001256

String

签约协议号

模板id

plan_id

123

String

协议模板id

用户标识

openid

onqOjjmM1tad-3ROpncN-yUfa6ua

String(32)

Appid下,用户的唯一标识

签名

sign

C380BEC2BFD727A4B6845133519F3AD6

String(32)

详见签名生成算法

变更类型

change_type

ADD

String(32)

有两个变更类型取值:
ADD--签约
DELETE--解约

操作时间

operate_time

2015-07-01 10:00:00

String

操作时间

委托代扣协议id

contract_id

Wx15463511252015071056489715

String(32)

签约成功后,微信返回的委托代扣协议id

协议到期时间

contract_expired_time

2016-07-01 10:00:00

String

协议到期时间,当change_type为ADD时有返回

协议解约方式

contract_termination_mode

3

Int

当change_type为DELETE时有返回
0-未解约
1-有效期过自动解约
2-用户主动解约
3-商户API解约
4-商户平台解约
5-注销

请求序列号

request_serial

1695

Int64

商户请求签约时的序列号,商户侧须唯一。序列号主要用于排序,不作为查询条件,纯数字,范围不能超过Int64的范围(9223372036854775807)。

示例:

<xml>
<return_code><![CDATA[SUCCESS]]></return_code>
<result_code><![CDATA[SUCCESS]]></result_code>
<sign><![CDATA[C380BEC2BFD727A4B6845133519F3AD6]]></sign>
<mch_id>10010404</mch_id>
<contract_code>100001256</contract_code>
<openid><![CDATA[onqOjjmM1tad-3ROpncN-yUfa6ua]]></openid>
<plan_id><![CDATA[123]]></plan_id>
<change_type><![CDATA[ADD]]></change_type>
<operate_time><![CDATA[2015-07-01 10:00:00]]></operate_time>
<contract_id><![CDATA[Wx15463511252015071056489715]]></contract_id>
</xml>

商户需返回参数

由于微信会多次通知商户服务器关于用户签约的结果和相关信息,为了避免给商户服务器造成过大的压力,请在得到微信签约结果通知之后,返回以下内容。(请求方式:post)

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

返回状态码

return_code

SUCCESS

String(16)

SUCCESS/FAIL
SUCCESS表示商户接收通知成功并校验成功

返回信息

return_msg

OK

String(32)

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

商户返回示例:

<xml>
  <return_code><![CDATA[SUCCESS]]></return_code>
  <return_msg><![CDATA[OK]]></return_msg>
</xml>
微信支付签约,解约通知出口IP列表

如果商户侧配置了防火墙,需要对商户回调通知功能开通下面白名单网段:
101.226.233.128/25