微信收款个人转账版服务接口文档

微信收款（个人转账版）服务

接口文档

1简介

为规范服务商下属个人用户的接入，服务商需将个人用户基本资料提交给微

信支付，微信支付返回下属个人用户的收款识别码。因为用户的数量较多，服务

商可以直接调用该系列API实现高效快捷的录入个人用户的资料。

2接口规则

协议规则详见

/wiki/doc/api/jsapi_?chapter=4_1

签名与算法详见

/wiki/doc/api/jsapi_?chapter=4_3

3API详细介绍

3.1新增收款个人用户资料API

服务商调用该接口将收款个人用户资料提交给微信侧，微信根据提交的

资料情况，判断收款用户资料正确性，返回收款识别码；

3.1.1接口URL

/secapi/mch/submchmanage?action=add

是否需要证书

需要

3.1.2请求参数

字段名

服务商公众账号ID

服务商商户号

签名

店铺名称

appid

mch_id

sign

merchant_name

变量名必填

是

是

是

是

类型

String(32)

String(32)

String(32)

String(128)

说明

微信分配的服务商账号ID

微信支付分配的服务商商户号

签名，详见签名生成算法

须与营业执照的名称保持一致，

最长为42个中文字符，128个

英文字符

店铺简称merchant_shortname是String(48)该名称将于支付成功页向消费者

进行展示，最长为16个中文字

符，48个英文字符

收款人姓名recipient_name是String(20)收款人姓名，姓名中间不能有空

格

收款人身份证recipient_idcardno是String(18)收款人身份证，

最长18位，数字+X

收款人微信号recipient_wechatid是String(32)需打开微信，在“个人信息”中

看到的“微信号”，操作指引见

图1，如“微信号”一栏显示“未

设置”，需先进行设置

经营类目business是String(12)传类目ID，须与实际售卖商品保

持一致，类目ID表内容见附录1

收款用户IDmerchant_remark是String(32)收款ID,是服务商系统内部的用

户ID，同一个服务商，其收款ID

需唯一。收款ID重复时，生成收

款识别码失败，建议使用服务商

管理用户时的系统内部唯一id

客服电话

店铺地址国标编码

service_phone

merchant_gbaddress

否

是

String(40)

String(6)

格式只能为数字加中杠

传地址对应的国标ID，

点击查看国标ID详情

店铺详细地址merchant_detailaddress是String(96)最长为32个汉字，96个英文字

符，例如：XX街道XX路XX号

联系人contact否String(20)联系人，以方便微信在必要时能

联系上商家

联系电话contact_phone否String(11)联系电话，以方便微信在必要时

能联系上商家

联系邮箱contact_email否String(60)联系邮箱，以方便微信在必要时

能联系上商家

3.1.2返回参数

字段名

返回状态码

变量名

return_code

必填

是

类型

String(16)

说明

SUCCESS/FAIL

此字段是通信标识，请求是否成

功需要查看result_code来判断

返回信息return_msg是String(128)返回信息为错误原因，如“签名

失败”，如成功返回“OK”

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

服务商商户号

处理结果

错误代码

mch_id

result_code

err_code

是

是

否

String(32)

String(32)

String(32)

微信支付分配的服务商商户号

SUCCESS/FAIL

result_code为FAIL时有返回，

详细参见错误码列表

错误代码描述err_code_des否String(128)result_code为FAIL时有返回，

详细参见错误码列表

签名sign是String(32)签名，详见签名生成算法

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

收款识别码micro_mch_id是String(32)微信支付分配的收款识别码

3.1.3错误码

错误码

NOT_UTF8

错误信息

XXX(字段名称)内容未使用UTF-8编码，请

检查后重试

说明

接口字段需使用UTF-8编码

PARAMS_FORMAT_ERROR1，XXX(字段名称)内容格式有误，请检查

后重试；

2，XXX(字段名称)超出限定字符串长度，

请检查后重试；

1，检查手机号码/身份证/姓名是

否有空格

2，检查字符串是否超出限定长度

BUSINESS_ERROR1，输入的类目ID有误，请查阅最新类目ID

表，检查后重试

2，输入的类目已不再对外开放，请查阅最

新类目ID表，检查后重试

1.检查类目ID是否正确；

2.检查当前类目ID是否是对外开

放状态

WECHATID_ERROR

WECHATID_BINDLIMIT

收款人微信号有误，请检查后重试

收款人微信号已绑定收款识别码，且绑定关

系条目数已达上限，请更换微信号后重试

检查收款人微信号是否正确

微信ID已有绑定多少个收款识别

码，一个微信号目前最多对应5个

收款识别码

WECHATID_NOT_REALNAME收款人微信号未进行实名认证，请绑定一张

银行卡后重试

检查微信号是否已进行实名

WECHATID_CHECK_ERROR收款人微信号实名信息与姓名、身份证信息

不匹配，请检查后重试

检查微信号实名信息是否与身份

证和姓名一致

请检查签名参数和方法是否都符

合签名算法要求

请尝试再次掉调用API。

SIGNERROR

签名错误

SYSTEMERROR接口返回错误

3.2查询收款个人用户资料API

服务商调用该接口通过传入“收款识别码”或“收款人微信号”，来获

取收款个人用户的相关资料信息

3.2.1接口URL

/secapi/mch/submchmanage?action=query

是否需要证书

需要

3.2.2请求参数

字段名

服务商公众账号ID

服务商商户号

收款识别码

收款人微信号

appid

mch_id

micro_mch_id

recipient_wechatid

二选一

变量名

是

是

必填类型

String(32)

String(32)

String(32)

String(32)

说明

微信分配的服务商公众账号ID

微信支付分配的服务商商户号

微信支付分配的收款识别码

需打开微信，在“个人信息”中

看到的“微信号”，操作指引见

图1，如“微信号”一栏显示“未

设置”，需先进行设置

签名sign是String(32)签名，详见签名生成算法

3.2.3返回参数

字段名

返回状态码

变量名

return_code

必填

是

类型

String(16)

说明

SUCCESS/FAIL

此字段是通信标识，请求是否成

功需要查看result_code来判断

返回信息return_msg是String(128)返回信息为错误原因，如“签名

失败”，如成功返回“OK”

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

服务商公众账号ID

服务商商户号

总记录数

签名

处理结果

错误代码

appid

mch_id

record_num

sign

result_code

err_code

是

是

是

是

是

否

String(32)

String(32)

String(10)

String(32)

String(32)

String(32)

微信分配的服务商公众账号ID

微信支付分配的服务商商户号

返回收款个人用户数据的个数

签名，详见签名生成算法

SUCCESS/FAIL

result_code为FAIL时有返回，

详细参见错误码列表

错误代码描述err_code_des否String(128)result_code为FAIL时有返回，

详细参见错误码列表

以下字段在result_code为SUCCESS的时候有返回,下标n从0开始

收款识别码

店铺名称

micro_mch_id_$n

merchant_name_$n

是

是

String(32)

String(128)

微信支付分配的收款识别码

须与营业执照的名称保持一致，

最长为42个中文字符，128个

英文字符

店铺简称merchant_shortname_$n是String(48)该名称将于支付成功页向消费者

进行展示，最长为16个中文字

符，48个英文字符

收款人姓名recipient_name_$n是String(20)收款人姓名，姓名中间不能有空

格

收款人身份证recipient_idcardno_$n是String(18)收款人身份证，

最长18位，数字+X

收款人微信号recipient_wechatid_$n是String(32)需打开微信，在“个人信息”中

看到的“微信号”，操作指引见

图1，如“微信号”一栏显示“未

设置”，需先进行设置

经营类目business_$n是String(12)传类目ID，须与实际售卖商品保

持一致，类目ID表内容见附录1

收款用户IDmerchant_remark_$n是String(32)收款用ID,是服务商系统内部的

用户ID，同一个服务商，其用户

ID需唯一。用户ID重复时，生

成收款识别码失败，建议使用服

务商管理用户时的系统内部唯一

id

客服电话

店铺国标编码地址

+详细地址

联系人

service_phone_$n

merchant_address_$n

否

是

String(40)

String(128)

格式只能为数字加中杠

最长为42个中文字符，128个

英文字符

contact_$n否String(20)联系人，以方便微信在必要时能

联系上商家

联系电话contact_phone_$n否String(11)联系电话，以方便微信在必要时

能联系上商家

联系邮箱contact_email_$n否String(60)联系邮箱，以方便微信在必要时

能联系上商家

3.2.4错误码

错误码

MICROMCHID_ERROR

WECHATID_ERROR

MICROMCHID_WECHATID_NOTMATCH

错误信息

收款识别码有误，请检查后重试

收款人微信号有误，请检查后重试

未找到搜索结果，请更换搜索条件

后重试

说明

检查收款识别码是否有误

检查收款人微信号是否有误

收款识别码与收款人微信号都输

入，但不匹配

请检查签名参数和方法是否都符

合签名算法要求

请尝试再次掉调用API。

SIGNERROR

签名错误

SYSTEMERROR接口返回错误

3.3下载付款账单API

服务商除可通过原有的“下载对账单”接口获取每天的收款明细外，我

们还提供“下载付款账单”接口，解决服务商和下挂收款个人的对账问题

注意：

1、下载‘付款账单’，bill_type固定传“PAYMENT”

2、微信在次日9点启动生成前一天的对账单，建议服务商10点后再获取

3、对账单中涉及金额的字段单位为“元”

3.3.1接口URL

/pay/downloadbill

是否需要证书

不需要

3.3.2请求参数

字段名

服务商公众账号ID

服务商商户号

平台商户号

随机字符串

签名

付款账单日期

appid

mch_id

sub_mch_id

nonce_str

sign

bill_date

变量名

是

是

是

是

是

是

必填类型

String(32)

String(32)

String(32)

String(32)

String(32)

String(8)

说明

微信分配的服务商公众账号ID

微信支付分配的服务商商户号

微信侧提供的固定平台商户号

随机字符串，不长于32位

签名，详见签名生成算法

下载付款账单的日期，格式：

20140603

账单类型bill_type是String(8)付款账单固定传“PAYMENT”

3.2.3返回结果

字段名

返回状态码

变量名

return_code

必填

是

类型

String(16)

说明

SUCCESS/FAIL

此字段是通信标识，请求是否成

功需要查看result_code来判断

返回信息return_msg否String(128)返回信息，如非空，为错误原因

签名失败；

参数格式校验错误；

该日期订单未生成；

成功时，数据以文本表格的方式返回，第一行为表头，后面各行为对应的字段内容：

表头格式为（付款时间,交易账单日期,收款识别码,店铺名称,应结算订单总金额,退款总金额,

手续费总金额,付款总金额,付款入账单号,零钱入账说明）

从第二行起，为数据记录，各参数以逗号分隔，参数前增加`符号，为标准键盘1左边键的

字符，字段顺序与表头一致。

举例如下：

付款时间交易账单日期

付款总金额

`2016-06-0822:04:56

收款识别码

`20160608

店铺名称应结算订单总金额退款总金额手续费总金额

付款入账单号零钱入账说明

`1341069201`小店888`60474.60`0.00`363.79

`60110.81`2213123`20160608_888_小店888的收款

3.4支付侧相关接口说明（只描述改动项）

1，所有接口中sub_mch_id字段统一传微信侧提供的固定平台商户号

1000077001

2，所有接口中attach字段统一代表“收款个人识别码”，

“收款个人识别码”通过调用“新增收款个人资料”接口，微信侧返回

对于收款个人，attach字段只能填写“收款个人识别码”且必须填写

3，收款个人暂不提供退款能力，“申请退款”，“退款查询”接口不可用

4，收款个人按实名个人单日收款限额五万,目前只要统一下单成功，即便用户不

支付也会累加限额，这里需要服务商增加主动关单的逻辑，设置一个合适的超时时间，对

并未支付成功的订单做主动关单的操作，关单成功后累加的限额便会扣除掉

5，支付侧相关接口新增错误码如下

错误码

OVER_PAYMENT_LIMIT

MICROMCHID_ERROR

NOAUTH

错误信息

超过收款个人买单收款限额5w

传入的收款识别码有误

该服务商没有收款个人的受理权

限

说明

收款个人单日收款限额五万

检查收款识别码是否有误

检查服务商收款个人的受理权限是否

已开通

检查服务商和收款个人是否存在受理

关系

检查attach字段是否传入了“收款识别码”

MCHID_MICROMCHID_NOT_MATCH该服务商和收款个人没有受理关

系

MICROMCHID_EMPTY本次交易必须传入收款识别码

图1：

如“微信号”一栏显示“未设置”，需先进行设置

附录1

类目ID表：

一级

餐饮/食品

餐饮/食品

教育/培训

苗木/绿化

票务/旅游

票务/旅游

票务/旅游

生活/家居

生活/家居

生活/家居

生活/家居

二级

食品

餐饮

教育/培训/考试缴费/学费

苗木种植/园林绿化

旅馆/酒店/度假区

娱乐票务

交通票务

户外/运动/健身器材/安防

母婴用品/儿童玩具

家装建材/家居家纺

美妆/护肤

品类ID

292

153

147

324

301

307

308

116

129

293

294

生活/家居

生活/家居

生活/家居

生活/家居

生活/家居

生活/家居

生活/家居

生活/家居

生活/咨询服务

生活/咨询服务

生活/咨询服务

生活/咨询服务

生活/咨询服务

生活/咨询服务

线下零售

线下零售

娱乐/健身服务

娱乐/健身服务

娱乐/健身服务

鲜花/盆栽/室内装饰品

交通工具/配件/改装

服饰/箱包/饰品

钟表/眼镜

宠物/宠物食品/饲料

数码家电/办公设备

书籍/音像/文具/乐器

计生用品

婚庆/摄影

装饰/设计

家政/维修服务

广告/会展/活动策划

咨询/法律咨询/金融咨询等

职业社交/婚介/交友

295

296

297

298

305

319

323

123

299

306

320

321

143

157

209

210

300

148

149

便利店

其他综合零售

俱乐部/休闲会所

美容/健身类会所

游艺厅/KTV/网吧