申请扣款

场景介绍

委托代扣可应用于定期扣款或需事后扣款以期提高效率的场景。例如公交,地铁等通过用户授权给商户,进行委托扣款的场景。
注:扣费请求首先按签约协议中记录的优先支付方式扣费,否则从可用扣款方式中依次选择扣款。

接口调用请求说明

请求Url https://api.mch.weixin.qq.com/transit/partnerpay/payapply
是否需要证书
请求方式 post
返回参数说明 扣款接口请求成功,返回success仅代表扣款申请受理成功,不代表扣款成功。扣款是否成功以支付通知的结果为准。

请求参数

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

公众账号id

appid

wxcbda96de0b165486

String(32)

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

子商户公众账号id sub_appid wxcbda96de0b165489 String(32) 微信分配的子商户公众账号ID

商户号

mch_id

10000098

String(32)

微信支付分配的商户号

子商户号 sub_mch_id 1900000109 String(32) 微信支付分配的子商户号

发起扣款时需要核实子商户号与用户状态查询子商户号是一致的

随机字符串

nonce_str

5K8264ILTKCH16CQ2502SI8ZNMTM67VS

String(32)

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

签名类型

sign_type

HMAC-SHA256

String(32)

签名类型,默认为HMAC-SHA256

签名

sign

EE088059BBC9141264F8D14293AD6C4BB94CEA8C08AA98FBF93E262D445F8FF5

String(64)

签名,详见签名生成算法

商品描述

body

公交代扣

String(128)

商品或支付单简要描述

商品详情

detail

公交代扣:A
公交代扣:B
公交代扣:C

String(6000)

商品名称明细列表

附加数据

attach

自定义参数

String(127)

附加数据,在查询API和支付通知中原样返回,该字段主要用于商户携带订单的自定义数据

商户订单号

out_trade_no

1217752501201407033233368018

String(32)

商户系统内部的订单号,32个字符内、可包含字母,

总金额

total_fee

888

int

订单总金额,单位为分,只能为整数

货币类型

fee_type

CNY

String(16)

符合ISO 4217标准的三位字母代码,默认人民币:CNY

终端IP

spbill_create_ip

8.8.8.8

String(16)

调用微信支付API的机器IP

商品标记

goods_tag

WXG

String(32)

商品标记,代金券或立减优惠功能的参数,说明详见代金券或立减优惠

回调通知url

notify_url

http://yoursite.com/wxpay.html

String(128)

接受扣款结果异步回调通知的url

交易类型

trade_type

PAP

String(16)

交易类型PAP-微信委托代扣支付

委托代扣协议id

contract_id

Wx15463511252015071056489715

String(32)

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

交易场景

trade_scene

METRO

String(16)

委托代扣的交易场景值,目前支持 :METRO:地铁场景; BUS:公交场景 。该值催缴时会向微信用户进行展示

场景信息

scene_info

{"scene_info":{"start_time":"20170826114339","end_time":"20170826114339","qrcode_hash":"a437d98bbf07bdde2942c99f6a2ab88a72b60aa747fce54b093c6","start_station":"西单","end_station":"天安门西"}}

String(1024)

场景信息值,格式为json,不同业务场景设置不同的值,具体如后面所列。

当trade_scene场景为:METRO 时,scene_info传如下值

乘车时间

start_time

20170826104339

String(32)

用户乘车时间(上车),格式为yyyyMMddHHmmss,地铁填地铁进站乘车时间,该值催缴时会向微信用户进行展示

下车时间

end_time

20170826114339

String(32)

用户下车时间yyyyMMddHHmmss

乘车码SHA256

qrcode_hash

a756836e7432437d98bbf07bdde2942c99f6a2ab88a72b60aa747fce54b093c6

String(64)

乘车码进行SHA256得到的字符串

起始站

start_station

西单

String(32)

乘车起始站,该值催缴时会向微信用户进行展示

终点站

end_station

天安门西

String(32)

乘车终点站,该值催缴时会向微信用户进行展示

当trade_scene场景为:BUS 时,传如下值

乘车时间

start_time

20170826104339

String(32)

用户乘车时间(上车),格式为yyyyMMddHHmmss,地铁填地铁进站乘车时间,该值催缴时会向微信用户进行展示

乘车路线

line_name

1路公车

String(32)

乘车路线
路线名称的展示规则:^[A-Za-z0-9]{1,10}路$
如line_name符合上述的规则,扣款凭证将增加展示乘车路线的字段

乘车码SHA256

qrcode_hash

a756836e7432437d98bbf07bdde2942c99f6a2ab88a72b60aa747fce54b093c6

String(64)

乘车码进行SHA256得到的字符串

车牌号

plate_number

粤B888888

String(32)

车牌号。仅包括省份+车牌,不包括特殊字符。

以下字段为非必填项风控参数,建议商户填写,提高风险控制能力

客户端 IP

clientip

119.145.83.6

String

点分IP格式(客户端IP)

设备ID

deviceid

baf04e6bbbd06f7b1a197d18ed53b7f1

String

android填imei的一次md5; ios填idfa的一次md5; 机具设备号

手机号

mobile

18933432355

String

用户手机号

邮箱地址

email

aobama@whitehouse.com

String

用户邮箱地址

QQ号

qq

100243

String

用户QQ号

微信open ID

openid

 

String

用户微信open ID

身份证号

creid

110102199701011000

String

用户身份证号

商户侧用户标识

outerid

 

String

用户在商户侧的标识

接口版本号

version

2.0

String(32)

接口版本号,区分原接口,若需要在⽀付结果 通知和还款回调通知中返回垫资信息,则在申 请扣费时固定填写2.0。注意,此字段仅针对有 垫资权限的商户有效。

数据示例:

<xml>
<mch_id>10000098</mch_id>
<sub_mch_id><![CDATA[10000100]]></sub_mch_id>
<appid>wxcbda96de0b165486</appid>
<nonce_str>5K8264ILTKCH16CQ2502SI8ZNMTM67VS</nonce_str>
<sign_type>HMAC-SHA256</sign_type>
<sign> EE088059BBC9141264F8D14293AD6C4BB94CEA8C08AA98FBF93E262D445F8FF5</sign>
<body>地铁代扣</body>
<out_trade_no>217752501201407033233368018</out_trade_no>
<total_fee>888</total_fee>
<spbill_create_ip>8.8.8.8</spbill_create_ip>
<notify_url>http://yoursite.com/wxpay.html</notify_url>       <trade_type>PAP</trade_type>
<contract_id>Wx15463511252015071056489715</contract_id>
<trade_scene>METRO</trade_scene>  <scene_info>{"scene_info":{"start_time":"20170826114339","end_time":"20170826114339","qrcode_hash":"a437d98bbf07bdde2942c99f6a2ab88a72b60aa747fce54b093c6","start_station":"西单","end_station":"天安门西"}}</ scene_info>
<version>2.0</version>
</xml>

返回参数

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

返回状态码

return_code

SUCCESS

String(16)

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

返回信息

return_msg

签名失败

String(128)

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

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

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

公众账号id

appid

wxcbda96de0b165486

String(32)

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

子商户公众账号id sub_appid

wxcbda96de0b165489 String(32) 微信分配的子商户公众账号ID

商户号

mch_id

10000098

String(32)

微信支付分配的商户号

子商户号 sub_mch_id

1900000109 String(32) 微信支付分配的子商户号

设备号

device_info

013467007045764

String(32)

终端设备号(门店号或收银设备ID),注意:PC网页或公众号内支付请传"WEB"

随机字符串

nonce_str

5K8264ILTKCH16CQ2502SI8ZNMTM67VS

String(32)

随机字符串,不长于32位。推荐随机数生成算法

签名

sign

C380BEC2BFD727A4B6845133519F3AD6

String(32)

生成签名方式详见签名生成详见签名生成算法

业务结果

result_code

SUCCESS

String(16)

SUCCESS/FAIL

错误代码

err_code

SIGN_ERROR

String(32)

错误码

错误代码描述

err_code_des

签名错误

String(32)

错误码描述

数据示例:

<xml>
<return_code><![CDATA[SUCCESS]]></return_code>
<return_msg><![CDATA[OK]]></return_msg>
<appid><![CDATA[wxcbda96de0b165486]]></appid>
<mch_id><![CDATA[10000098]]></mch_id>
<sub_mch_id><![CDATA[10000100]]></sub_mch_id>
<nonce_str><![CDATA[IITRi8Iabbblz1Jc]]></nonce_str>
<sign><![CDATA[EE088059BBC9141264F8D14293AD6C4BB94CEA8C08AA98FBF93E262D445F8FF5]]></sign>
<result_code><![CDATA[SUCCESS]]></result_code>
< /xml>

错误码

名称

描述

原因

解决方案

名称

描述

原因

解决方案

SYSTEMERROR

接口返回错误

系统超时

请使用相同参数再次调用API。

重试策略,共10次,每次间隔时间:

30秒,60秒,60秒,120秒,120秒,180秒,180秒,360秒,360秒,600秒

CONTRACT_NOT_EXIST

签约协议不存在

签约协议号不存在

请检查签约协议号是否正确

PARAM_ERROR

参数错误

请求参数未按指引进行填写

请根据接口返回的详细信息检查您的程序

INVALID_REQUEST

非法请求

非法请求

请检查请求参数、商户权限等是否正确

OUT_TRADE_NO_USED

商户订单号重复

同一笔交易不能多次提交

请核实商户订单号是否重复提交

ORDER_PAID

订单已支付

订单号重复

请确认该订单号是否重复支付,如果是新单,请使用新订单号提交

ORDER_ACCEPTED

扣款请求已受理,请勿重复发起

该订单已发起过扣款申请,无需再次请求

请调用查询订单接口查看订单最新状态

ORDER_CLOSED

订单已关闭

该订单已关

商户订单异常,请重新下单支付

SIGN_ERROR

签名错误

参数签名结果不正确

请检查签名参数和方法是否都符合签名算法要求

CONTRACT_OVER_LIMIT

用户支付超出限额

支付笔数、或支付金额超出代扣限额

请检查当前扣款金额,扣款次数。

REQUEST_BLOCKED

请求被拒绝

用户欠费或者不符合微信免密业务要求

提示用户到微信进行还款,后可继续使用务业

PAYAUTH_ERROR

权限校验错误

商户号产品权限校验错误

权限校验错误 服务商或子商户号权限校验错误 请检查如下三个权限:
1.服务商商户号受理权限
2.子商户号代扣产品权限
3.子商户号授予父商户号代扣权限

TRADE_ERROR

支付确认失败

用户的微信号被风控拦截或者用户的微信号被紧急冻结

提示用户可咨询微信客服了解具体原因