商户进件
特约商户进件
基础支付
JSAPI支付
APP支付
H5支付
Native支付
小程序支付
合单支付
付款码支付
经营能力
支付即服务
点金计划
行业方案
电商收付通(商户进件)
电商收付通(普通支付)
电商收付通(合单支付)
电商收付通(分账)
电商收付通(补差)
电商收付通(退款)
电商收付通(余额查询)
电商收付通(商户提现)
电商收付通(跨境付款)
电商收付通(下载账单)
智慧商圈
微信支付分停车服务
营销工具
代金券
商家券
委托营销
支付有礼
小程序发券插件
H5发券
图片上传(营销专用)
现金红包
资金应用
分账
连锁品牌分账
风险合规
商户开户意愿确认
消费者投诉2.0
商户违规通知回调
其他能力
图片上传
视频上传
微信支付平台证书

导入定向用户协议号API

最新更新时间:2021.09.23 版本说明

创建快捷交易协议号上传任务,每个上传任务中需要上传一个快捷交易协议号文件。微信收到快捷交易协议号文件后,会识别出其中的微信用户,保存到指定的号码包中。一个号码包可以包含多个上传任务,这些上传任务导入的用户会被合并去重,再追加写到号码包。

接口说明

适用对象:服务商

请求URL:https://api.mch.weixin.qq.com/v3/marketing/bank/packages/{package_id}/tasks

请求主体类型:multipart/form-data

请求方式:POST


path 指该参数为路径参数

query 指该参数需在请求URL传参

body 指该参数需在请求JSON传参


请求参数

参数名 变量 类型[长度限制] 必填 描述
号码包id package_id string[4, 16] path号码包唯一标识符。可在微信支付商户平台创建号码包后获得。
示例值:8473295
+快捷交易协议号文件 file object body将快捷交易协议号文件进行二进制转换,得到的二进制内容,在请求body中上传此二进制内容。只支持TXT或CSV格式的纯文本文件,每行一个加密后的协议号,换行符使用\n,编码格式使用utf-8。使用微信支付平台证书中的公钥逐个加密协议号。文件大小不能超过2MB,建议单个文件的行数不超过5500行。同一个号码包的多个上传任务的文件名不可重复。
参数名 变量 类型[长度限制] 必填 描述
文件名 content string 任务上传的文件
文件类型 content_type string 任务上传的文件类型
文件名 filename string 任务上传的文件名
+文件元信息 meta object body快捷协议号包的文件元信息
参数名 变量 类型[长度限制] 必填 描述
银行类型 bank_type string[1, 32] 银行类型,用于标识协议号所属的银行以及卡类型(信用卡或借记卡)。采用字符串类型的银行标识,值列表详见银行类型
示例值:ICBC_DEBIT
文件名 filename string[4, 128] 快捷协议号包文件名。可包含英文字母,数字,_,.,-等内容,不允许出现其他不合法符号。同一个号码包的多个上传任务的文件名不可重复,要保证唯一
示例值:active_user.csv
文件摘要 sha256 string[64, 64] 快捷交易协议号文件的文件摘要,即快捷交易协议号文件的二进制内容进行sha256计算得到的值
示例值:addca90a6a290b9642dbaccffdf01e8c22aa348940b2e96754169ba08c19e5db

各语言请求示例

---示例代码待更新---

返回参数

参数名 变量 类型[长度限制] 必填 描述
银行类型 bank_type string[1, 32] 银行类型,用于标识协议号所属的银行以及卡类型(信用卡或借记卡)。采用字符串类型的银行标识,值列表详见银行类型
示例值:ICBC_DEBIT
创建上传任务的时间 create_time string[8, 32] 时间格式采用遵循rfc3339标准格式,格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE,yyyy-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss表示时分秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35.+08:00表示,北京时间2015年5月20日 13点29分35秒。
示例值:2020-05-20T13:29:35+08:00
失败数 fail_count int 匹配失败的协议号数。仅当任务状态是FINISHED时,该数据才有效
示例值:20
文件名 filename string[4, 128] 任务上传的文件名
示例值:active_user.csv
号码包id package_id string[4, 16] 号码包唯一标识符。可在微信支付商户平台创建号码包后获得。
示例值:8473295
任务状态 status string[1, 16] 上传任务的状态
PROCESSING:处理中,上传任务处理中,请等待
FINISHED:已完成,上传任务已处理完成,任务上传的文件中的用户已导入到号码包中
示例值:PROCESSING
成功数 success_count int 匹配成功的协议号数。仅当任务状态是FINISHED时,该数据才有效
示例值:1000
匹配成功的微信用户数 success_user_count int 匹配成功的微信用户数,不小于匹配成功的协议号数。当一张银行卡被用户绑定到不同微信号时,才可能出现一个协议号对应多个微信账户的情况。仅当任务状态是FINISHED时,该数据才有效
示例值:1000
上传任务 task_id string[1, 16] 上传任务的主键,唯一定义此资源的标识
示例值:101
上传任务最近一次更新的时间 update_time string[8, 32] 时间格式采用遵循rfc3339标准格式,格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE,yyyy-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss表示时分秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35.+08:00表示,北京时间2015年5月20日 13点29分35秒。
示例值:2020-05-20T13:29:35+08:00

返回示例


{
  "bank_type": "ICBC_DEBIT",
  "create_time": "2020-05-20T13:29:35+08:00",
  "fail_count": 20,
  "filename": "active_user.csv",
  "package_id": "8473295",
  "status": "PROCESSING",
  "success_count": 1000,
  "success_user_count": 1000,
  "task_id": "101",
  "update_time": "2020-05-20T13:29:35+08:00"
}
                    

http://2323weixin.qq.com
                    

请求步骤

快捷交易协议号文件格式说明

快捷交易协议号文件内容需要遵循特定格式,才能够正确解析和识别为微信用户。

格式说明:

1、为保证数据安全,快捷交易协议号需要加密后上传。加密方法可参考敏感信息加解密,使用微信支付平台证书中的公钥,逐个加密快捷交易协议号。

2、文件内容:每行一个加密后的快捷交易协议号,换行符使用\n,不能使用\r\n,不允许包含空行。

3、文件大小不能超过2MB,建议单个文件的行数不超过5500行。

文件上传步骤:

1.创建一个POST的方法请求/upload URI

例如: POST https://api.mch.weixin.qq.com/v3/marketing/bank/packages/{package_id}/tasks HTTP/1.1


2.将文件的数据添加到请求主体

2.1 文本文件file参数的获取方式说明:
文本文件二进制内容,放在请求http的body中。


2.2 文本文件元信息meta参数的获取方式说明:
文本文件元信息,使用json表示,包含三个对象:bank_type、filename、sha256。
● bank_type参数获取方式说明:
银行类型,用于标识协议号所属的银行以及卡类型(信用卡或借记卡)。采用字符串类型的银行标识,值列表详见银行类型
● filename参数获取方式说明:
快捷协议号包文件名。可包含英文字母,数字,_,.,-等内容,不允许出现其他不合法符号。同一个号码包的多个上传任务的文件名不可重复,要保证唯一
● sha256参数获取方式说明:
快捷交易协议号文件的文件摘要,即快捷交易协议号文件的二进制内容进行sha256计算得到的值


2.3 签名计算说明:
签名生成
参与签名计算的请求主体为meta的json串:
{ "bank_type": "ICBC_DEBIT","filename": "active_user.csv", "sha256": "hjkahkjsjkfsjk78687dhjahdajhk" }


待签名串示例:

POST
/v3/marketing/bank/packages/{package_id}/tasks
1566987169           //时间戳
12ced2db6f0193dda91ba86224ea1cd8   //随机数
{ "bank_type": "ICBC_DEBIT","filename": "active_user.csv", "sha256": "hjkahkjsjkfsjk78687dhjahdajhk" }

3.添加HTTP头:


Content-Type:multipart/form-data.设置为要上载的对象的MIME媒体类型。
Authorization: WECHATPAY2-SHA256-RSA2048 mchid="1900231671",
nonce_str="PCHK6HSOEDTACETP6P3AL7DWPHTBKIAT",timestamp="1567067659",
serial_no="1FB89742D19F2BD30B69948D16DECA0FCB4481EB",
signature="PB6M7+3JL7TSCl5zqD1sdWVypOIEQsD4dgOU+vPiVM6GMRo2qYSWKf8u46i9ZJFhyZTBdZ7SFR+BjDZh6
89hFgN8LZL+QWTvq3cse/FEUFYyOLN7L/2IZX4GA4cWInuJ2MpOhZRMpm+emrcn42gTMKAPNQ7dBLO7ux6MoSuQp69
PW+p1ogmkER68exTVUXYqA5P3vITlWNr++RDy2+ExvB7qVISOKW0vBkxUxN9e7hwUbDwGln170ZXomoO1KpQSbw3f1u
WUCx/IlWJhJIun7rUMtVT+kfijNUqcILtSfE4hWKKVaZn9j5CX8M7aKbbDOFy3SvbSJ3WQgRnRbgog5w=="
Content-Type: multipart/form-data;boundary=boundary

4.添加body:


// 以下为body的内容
--boundary  // boundary为商户自定义的一个字符串
Content-Disposition: form-data; name="meta";
Content-Type: application/json
//此处必须有一个空行
{ "bank_type": "ICBC_DEBIT","filename": "active_user.csv", "sha256": "hjkahkjsjkfsjk78687dhjahdajhk" }
--boundary
Content-Disposition: form-data; name="file"; filename="active_user.csv";
Content-Type: text/plain
//此处必须有一个空行
cvs  //cvs即为快捷交易协议号文件的二进制内容
--boundary--

说明:请求包体每行结尾都需要包含\r\n(空行也需要)。


5.发送请求


POST /v3/marketing/bank/packages/{package_id}/tasks HTTP/1.1
Host: api.mch.weixin.qq.com
Authorization: WECHATPAY2-SHA256-RSA2048 
mchid="1900231671",nonce_str="PCHK6HSOEDTACETP6P3AL7DWPHTBKIAT",
timestamp="1567067659",
serial_no="1FB89742D19F2BD30B69948D16DECA0FCB4481EB",
signature="PB6M7+3JL7TSCl5zqD1sdWVypOIEQsD4dgOU+vPiVM6GMRo2qYSWKf8u46i9ZJFhyZTBdZ7
SFR+BjDZh689hFgN8LZL+QWTvq3cse/FEUFYyOLN7L/2IZX4GA4cWInuJ2MpOhZRMpm+emrcn42gTMKAPN
Q7dBLO7ux6MoSuQp69PW+p1ogmkER68exTVUXYqA5P3vITlWNr++RDy2+ExvB7qVISOKW0vBkxUxN9e
7hwUbDwGln170ZXomoO1KpQSbw3f1uWUCx/IlWJhJIun7rUMtVT+kfijNUqcILtSfE4hWKKVaZn9j5CX8M
7aKbbDOFy3SvbSJ3WQgRnRbgog5w=="
Content-Type: multipart/form-data;boundary=boundary

--boundary  
Content-Disposition: form-data; name="meta";
Content-Type: application/json

{ "bank_type": "ICBC_DEBIT","filename": "active_user.csv", "sha256": "hjkahkjsjkfsjk78687dhjahdajhk" }
--boundary
Content-Disposition: form-data; name="file"; filename="active_user.csv";
Content-Type: text/plain

cvs
--boundary--

错误码公共错误码

状态码 错误码 描述 解决方案
400 PARAM_ERROR HTTP header缺少微信支付平台证书序列号(Wechatpay-Serial) 将加密快捷交易协议号时所使用的平台证书的序列号,设置到HTTP头部的Wechatpay-Serial
400 INVALID_REQUEST 号码包id未填或格式不正确 url中的号码包id错误,请检查
文件内容为空 请在文件中填充加密后的快捷交易协议号,每行一个,使用\n作换行符,然后再上传
文件大小超出限制,请分成多个文件上传 文件大小不能超过限制,可分割成若干小文件再上传
meta和file中的文件名不一致 请参考示例设置请求参数
基于文件内容计算的sha256与meta传入的sha256不相等 请商户确认文件摘要是否正确计算
文件的换行符不支持\r\n,请使用\n 请使用\n换行符
文件不允许存在空行 先删掉空行,再重新上传
不支持的银行类型,请检查并重试 参考确认银行类型的正确性
同一号码包不可重复上传同名文件 先确认文件内容是否重复,如果是新内容,请重新命名后上传
404 NOT_FOUND 未找到指定号码包 请商户确认号码包是否由自己创建,只能由创建方导入定向用户协议号
500 SYSTEM_ERROR 系统错误 系统异常,请使用相同参数稍后重新调用


技术咨询

文档反馈