# 一、简介与准入开通
# 1. 功能简介
小程序B2b门店助手是由微信官方提供的，帮助品牌商或经销商连接并管理终端门店的免费工具。品牌商或经销商小程序接入后，经用户（门店）认证授权，可帮助品牌商或经销商：
1）便捷获取门店真实信息
2）针对门店进行促销、活动以及订单等场景的消息触达
3）获取B2b支付能力
详情可参考小程序B2b门店助手产品功能介绍
# 2. 准入规则
小程序的服务类目含有：商家自营-B2b(商品批发/门店管理)。具体类目请参考小程序商家适用类目
# 3. 开通流程
方式1：小程序后台开通
成功申请开通类目（商家自营-B2b(商品批发/门店管理)）的小程序，登录小程序后台（mp.weixin.qq.com），按照“侧边栏-功能-门店助手”的路径，申请开通门店助手功能权限。
方式2：服务商代开通
Step1、服务商需通过第三方平台账号,获取小程序的门店助手功能权限集（权限集ID：158，权限集名称：小程序B2b门店助手）
Step2、服务商获得权限集授权后，可通过使用authorizer_access_token代商家调用。成功开通后，服务商即可代小程序开发所有门店助手相关功能。
注意事项
1）该接口所属权限集 id 为 158
2）服务商获得权限集授权后，可通过使用 authorizer_access_token 代商家调用
调用方式
HTTPS 调用
POST https://api.weixin.qq.com/wxa/business/retailbusinessapply?access_token=AUTHORIZER_ACCESS_TOKEN
请求参数
| 属性 | 类型 | 必填 | 说明 |
|---|---|---|---|
| access_token | string | 是 | 接口调用凭证，该参数为 URL 参数，非 Body 参数。使用 authorizer_access_token |
| goods_type_list | array<string> | 是 | 主营商品类型。 可选项： "食品", "饮料", "乳制品", "酒水", "生鲜果蔬", "调味品", "日化个护", "文具", "鞋服/配饰", "家居", "母婴/玩具", "数码3C", "其他" |
| goods_sale_list | array<string> | 是 | 主要线下销售渠道。 可选项： "杂货店", "便利店", "超市", "餐饮店", "母婴店", "烟酒店", "其他" |
| cover_num | string | 是 | 门店覆盖数。 可选项： "0-5千", "5千-1万", "1万-10万", "10万-50万", "50万以上" |
| service_list | array<string> | 是 | 所需服务类型。 可选项： "门店订货", "门店促销", "门店活动执行", "门店直播", "其他" |
| description | string | 是 | 小程序方案概述。长度限制：21-100字 |
| contact_name | string | 是 | 联系人姓名。长度限制：1-7字。 |
| contact_phone | string | 是 | 联系人手机号 |
| contact_email | string | 是 | 联系人邮箱 |
返回参数
| 属性 | 类型 | 说明 |
|---|---|---|
| errcode | number | 错误码。 |
| errmsg | string | 错误原因。 |
调用示例
请求数据示例
{
"goods_type_list": ["食品", "其他"],
"goods_sale_list": ["杂货店", "便利店", "超市"],
"cover_num": "0-5千",
"service_list": ["门店订货"],
"description": "使用订货功能，线上下单、配送到店；小程序开发者可以通过消息能力，发送新品上线、活动消息等到小店，引导其跳转到小程序内查看活动信息或者订货",
"contact_name": "张三",
"contact_phone": "13712345678",
"contact_email": "zhangsan@qq.com"
}
返回数据示例
{
"errcode": 0,
"errmsg": "ok"
}
常见错误码
| errcode | 说明 |
|---|---|
| 0 | 成功开通 |
| 9404201 | 无效的主营商品类型 |
| 9404202 | 无效的主要线下销售渠道 |
| 9404203 | 无效的门店覆盖数 |
| 9404204 | 无效的所需服务类型 |
| 9404205 | 无效的小程序方案概述 |
| 9404206 | 无效的联系人姓名 |
| 9404207 | 无效的联系人手机号 |
| 9404208 | 无效的联系人邮箱 |
| 9404209 | 该账号不满足申请条件 |
| 9404210 | 已申请，请耐心等待 |
# 二、开发指引
# 1. 门店认证授权
引用门店助手插件，引导用户完成认证授权
在小程序的流程设计中，引导用户进入”小程序门店助手“插件页面，完成门店认证授权流程。只有对完成门店信息授权的用户，开发者方可适用门店助手的能力，包括：
1）获取门店真实信息
2）针对门店进行促销、活动以及订单等场景的消息触达
3）获取B2b支付能力
示例：
# 1.1 申请添加插件
方式1：小程序后台页面申请
登录小程序后台（mp.weixin.qq.com），选择菜单“设置-第三方设置-插件管理-添加插件”，搜索“小程序门店助手”并申请添加。
方式2：开发者工具引用
使用开发者工具运行小程序，并引入插件，在调试器中会提示“添加插件”，点击添加插件，前往小程序管理后台确认即可.
# 1.2 配置插件
在小程序app.json中配置
重要提醒：version可以填写具体版本号，建议直接填写latest以自动获取最新版插件
注意：“自定义插件名”代表之后使用时需要配置的，文档中使用了"bb-plugin"作为演示。 还需要添加 permission 字段来允许使用定位信息，才可以选择门店地址。
{
"pages": [
"pages/index/index"
],
"plugins": {
"自定义插件名": {
"version": "latest",
"provider": "wx69b7451feb427f0e"
}
},
"sitemapLocation": "sitemap.json",
"permission": {
"scope.userLocation": {
"desc": "你的位置信息将用于小程序定位"
}
}
}
# 1.3 代码中添加插件入口
页面中会出现“打开插件”的导航，点击可跳转门店认证插件。
示例中的“bb-plugin”就是在app.json里面配置的自定义的插件名。
<!--index.wxml-->
<navigator url="plugin://bb-plugin/info-regist">
打开插件
</navigator>
# 1.4 获取插件授权信息
备注：若用户未向该小程序授权门店认证信息，则会返回错误信息“门店未对品牌授权”。
const plugin = requirePlugin("bb-plugin"); // 引入插件
Page({
data: {
},
onShow(){
plugin.getRetailInfo({
success: (value) => {
console.log(value)
}
})
}
});
// value 结构如下
{
"status": true,
"errorMsg": "成功",
"data": {
"isEnableUsePlugin": true,
"isGrantRetailInfo": true,
"phone": "18888888888",
"storeType": "超市",
"storeAddress": "广东省广州市海珠区创意大道",
"businessName": "测试店名 A",
"businessId": "223345jjj123445C",
"managerName": "路人甲",
"openid": "ooo999=ssssdxdf",
"managerAuditStatus": 4
}
}
# 1.5 插件返回的授权信息
返回结构体字段：
| 参数意义 | 返回参数 | 备注 |
|---|---|---|
| 调用状态 | status | 若未授权则为 false |
| 返回数据 | data | |
| 错误信息 | errorMsg |
返回数据字段：
| 参数意义 | 参数名称 | 类型 |
|---|---|---|
| 该小程序是否允许使用此插件 | isEnableUsePlugin | boolean |
| 该小程序是否已被授权 | isGrantRetailInfo | boolean |
| 门店登记手机号 | phone | string |
| 门店类型 | storeType | string |
| 门店地址 | storeAddress | string |
| 门店名称 | businessName | string |
| 营业执照注册号 | businessId | string |
| 经营者姓名 | managerName | string |
| 用于发送消息的id | openid | string |
# 1.6 预录入门店信息api
接口功能：通过本API可提前预录入门店信息。
场景说明：对于已提前预录入门店信息的用户，在登录小程序进行门店认证授权流程时，会默认拉起展示预录入的门店信息，用户一键确认即可完成认证授权，减少用户操作成本，提示认证授权成功率。
所有API调用前，需要先获取“接口调用凭证”。
调用方式:
HTTPS 调用
POST https://api.weixin.qq.com/wxa/business/batchcreateretail?access_token=ACCESS_TOKEN
如调用本接口返回错误码4：地址解析失败，可将导入失败的地址数据传入地址解析接口（地址解析接口文档），获取标准化的省、市、区后重新导入。
附：门店助手有效地址组合
请求参数说明：
| 参数 | 说明 | 备注 |
|---|---|---|
| retail_info_list | 门店信息列表 | 每次调用最多可导入100个门店，多于则返回错误。每个门店信息所需字段： mobile_phone：手机号【必填】 retail_name：门店名称（长度为1-30个字符，一个中文字等于2个字符）【必填】 retail_type：一级门店类型（杂货店、便利店、超市、餐饮店、母婴店、烟酒店、其他） sub_retail_type：二级门店类型（一级门店类型为“其他”时必填） address_province：门店地址，省【必填】address_city：门店地址，市【必填】 address_region：门店地址，区县【必填】 address_street：门店地址：街道详细地址【必填】 registration_number：营业执照注册号 biz_name：企业名称 corporation_name：法人姓名 latitude：纬度 longitude：经度 |
字段内容举例：
curl -d '{"retail_info_list": [{"mobile_phone": "12345678910", "retail_name": "烧烤店", "retail_type": "餐饮店", "address_province": "广东省", "address_city": "广州市", "address_region": "海珠区", "address_street": "新港中路397号TIT创意园","longitude": 113.32531, "latitude": 23.0996132}]}' -i https://api.weixin.qq.com/wxa/business/batchcreateretail?access_token=xxx
请求示例：
{
"retail_info_list": [
{
"mobile_phone": "12345678910",
"retail_name": "张三烧烤店",
"retail_type": "餐饮店",
"address_province": "广东省",
"address_city": "广州市",
"address_region": "海珠区",
"address_street": "新港中路397号TIT创意园",
"longitude": 113.32531,
"latitude": 23.0996132
},
{
"mobile_phone": "a123456789",
"retail_type": "便利店",
"address_province": "广东省",
"address_city": "广州市",
"address_region": "海珠区",
"address_street": "新港中路397号TIT创意园",
"registration_number": "xxxxx",
"biz_name": "xxxxx",
"corporation_name": "xxxxx"
}
]
}
返回数据示例：
{
"errcode": 0,
"errmsg": "ok",
"num_success": 1,
"num_failure": 1,
"failure_record_list": [
{
"mobile_phone": "a123456789",
"registration_number": "",
"failure_code": 6
}
]
}
errcode返回值及含义：
| 返回值 | 含义 |
|---|---|
| -1 | 系统繁忙，请稍后重试 |
| 0 | 成功 |
| 40001 | token 无效 |
| 48001 | 小程序无该api权限，反馈给对接人开通 |
| 9404000 | 上传数量过多 |
| 9404001 | 门店信息参数缺失 |
failure_code含义：
| 返回值 | 含义 |
|---|---|
| 2 | 无效的手机号 |
| 3 | 无效的门店类型 |
| 4 | 地址解析失败 |
| 5 | 手机号已被录入门店信息 |
| 6 | 无效的门店名称（长度限制为1-30个字符，一个中文字等于2个字符） |
# 1.7 门店信息查询api
接口功能：查询已完成门店认证授权用户的门店信息
调用方式:
HTTPS 调用
POST https://api.weixin.qq.com/wxa/business/getretailinfo?access_token=ACCESS_TOKEN
请求参数说明：
| 参数 | 说明 | 备注 |
|---|---|---|
| openid | 门店负责人openid | 两个参数二选一，若都填写，优先使用 openid |
| mobile_phone | 手机号 |
响应参数说明：
| 参数 | 说明 | 备注 |
|---|---|---|
| mobile_phone | 手机号 | |
| retail_type | 一级门店类型 | |
| sub_retail_type | 二级门店类型 | |
| retail_address | 门店地址 | |
| retail_name | 门店名称 | |
| identification | 营业执照注册号 | |
| principal | 企业名称 | |
| legal_person_name | 法人姓名 | |
| openid | 门店负责人openid | |
| status | 认证状态 | 1：已完成认证 |
| auth_time | 认证时间 | 认证完成那一刻的时间戳 |
| grant_time | 授权时间 | 授权给小程序那一刻的时间戳 |
| longitude | 经度 | 门店定位信息。若门店未提交定位信息，则返回值里无该字段 |
| latitude | 纬度 | 门店定位信息。若门店未提交定位信息，则返回值里无该字段 |
字段内容举例：
curl -d '{"openid": "xxxxx"}' -i https://api.weixin.qq.com/wxa/business/getretailinfo?access_token=xxx
请求示例：
{
"openid": "xxxxx"
}
返回数据示例：
{
"errcode": 0,
"errmsg": "ok",
"info": [
{
"mobile_phone": "12345678910",
"retail_type": "餐饮店",
"sub_retail_type": ""
"retail_address": "广东省广州市海珠区新港中路397号TIT创意园",
"retail_name": "张三烧烤店",
"identification": "100000000000000001",
"principal": "广州张三烧烤店",
"legal_person_name": "张*",
"openid": "xxxxxxxxxx",
"status": 1,
"auth_time": 1655458898,
"grant_time": 1655458909,
"longitude": 113.32531,
"latitude": 23.0996132
}
]
}
errcode返回值及含义：
| 返回值 | 含义 |
|---|---|
| -1 | 系统繁忙，请稍后重试 |
| 0 | 成功 |
| 40001 | token 无效 |
| 48001 | 小程序无该api权限，反馈给对接人开通 |
| 9404101 | 非法参数 |
| 9404102 | 该店主不存在、未认证或者未授权给你 |
| 9404103 | 请求过于频繁，请稍后重试 |
# 1.8 全量授权门店查询api
调用方式
HTTPS 调用
POST https://api.weixin.qq.com/wxa/business/getretailopenidlist?access_token=ACCESS_TOKEN
请求参数
| 属性 | 类型 | 必填 | 说明 |
|---|---|---|---|
| access_token | string | 是 | 接口调用凭证，该参数为 URL 参数，非 Body 参数。使用 getAccessToken 或者 authorizer_access_token |
| limit | number | 是 | 分页拉取最大返回结果数。取值范围：1-100 |
| page_context | string | 是 | 分页上下文。每轮遍历的首次调用传空值，后续调用填上一次调用返回参数的 page_context |
返回参数
| 属性 | 类型 | 说明 |
|---|---|---|
| errcode | number | 错误码。 |
| errmsg | string | 错误原因。 |
| openid_list | array<string> | openid 列表 |
| page_context | string | 分页上下文 |
调用示例
请求数据示例
{
"limit": 100,
"page_context": ""
}
返回数据示例
{
"errcode": 0,
"errmsg": "ok",
"openid_list": ["openid1", "openid2", "..."],
"page_context": "page_context1"
}
常见错误码
| errcode | 说明 |
|---|---|
| 0 | 成功 |
| 9404151 | 无效的分页拉取最大返回结果数 |
| 9404152 | 无效的分页上下文 |
# 1.9 常见QA
1、预录入门店信息后，调取信息完成认证正确方式，以及为什么会出现报错情况？
答：①品牌帮预录入门店信息：假设手机A被品牌预录入门店信息，任何微信号都可以登录手机A+验证码获取门店信息。一旦门店信息被调取，就需要用最初登录手机A调取门店信息的微信号继续完成认证，否则使用其他微信号会报错。
②门店自行预录入门店信息：假设微信号A登录手机B+验证码预录入过门店部分信息后退出插件，后面使用别的微信号登录手机B+验证码调取之前预录入信息继续完成认证是会报错的，需要用最初微信号A登录手机号B＋验证码方可调取。
注：无论是哪种预录入情况，完成门店认证流程并认证成功，任何微信都可以调取同一个手机号+验证码获取已认证门店信息和进行门店信息修改
# 2. 消息触达
# 2.1 模板消息交互说明
用户（门店）完成认证授权后，开发者可对用户（门店）利用模板消息进行触达。
发送方式：
1）api发送模板消息：调用消息接口，向指定用户发送模板消息
2）mp后台群发功能：在mp后台页面投放端，可创建面向指定用户群体的群发任务
# 2.2 模板消息列表及下发api
调用方式
HTTPS 调用
POST https://api.weixin.qq.com/wxa/business/retailnotifybusiness?access_token=ACCESS_TOKEN
模板列表
- 1. 门店物料申请进度通知（不限下发次数）
- 2. 门店订单发货通知（不限下发次数）
- 3. 门店订单派送通知（不限下发次数）
- 4. 门店认证进度通知（不限下发次数）
- 5. 门店订货活动通知（单门店可被发送上限：8次/月）
- 6. 门店陈列任务通知（单门店可被发送上限：4次/月）
- 7. 门店营销任务通知（单门店可被发送上限：4次/月）
- 8. 门店任务进展通知（单门店可被发送上限：1次/日）
- 9. 优惠券到期提醒（单门店可被发送上限：4次/月）
- 10. 积分到期提醒（单门店可被发送上限：4次/月）
- 11. 兑换券到期提醒（单门店可被发送上限：4次/月）
- 12. 门店调研通知（单门店可被发送上限：4次/月）
# 门店物料申请进度通知
发送频次：（不限下发次数）
| 参数 | 说明 | 备注 |
|---|---|---|
| type | 消息类型 | 门店物料申请进度通知，填7 |
| content | 消息内容的json字符串 | content内的各个字段含义： content：通知内容 keyword.DATA people：申请人 keyword.DATA date：申请时间 keyword.DATA delivery：配送商 keyword.DATA path：模板消息的跳转路径（只能跳转到当前调用api的小程序内路径，这里填小程序内的path即可。选填，默认跳转首页） img_url：小程序商家助手菜单栏“我要订货”页面banner展示，只能用上传图文消息内的图片获取URL--微信开放文档接口生成的链接，选填 business_msg_id: 自定义的消息id（选填，string类型，长度<20，建议英文或数字） |
| to_user_list | 门店负责人openid列表 | 门店负责人openid列表，最多一次发送200个openid |
注：对于keyword.DATA等”模板消息参数值内容限制说明“参见该链接：模板消息--微信开放文档
请求示例：
{
"type": 7,
"content": "{
\"content\":\"你申请的冰柜已发货\",
\"people\":\"小林\",
\"date\":\"2023年2月1日\",
\"delivery\":\"京东\",
\"path\":\"pages/xxxxx\",
\"img_url\":\"xxxxx\",
\"business_msg_id\":\"eg123456\"
}",
"to_user_list":[
"xxxxxxxxxxxxxx"
]
}
返回示例：
{
"errcode": 0,
"errmsg": "OK"
}
# 门店订单发货通知
发送频次：（不限下发次数）
| 参数 | 说明 | 备注 |
|---|---|---|
| type | 消息类型 | 门店订单发货通知，填8 |
| content | 消息内容的json字符串 | content内的各个字段含义： content：订单内容 keyword.DATA amount：订单金额 keyword.DATA delivery：配送商 keyword.DATA path：模板消息的跳转路径（只能跳转到当前调用api的小程序内路径，这里填小程序内的path即可。选填，默认跳转首页） img_url：小程序商家助手菜单栏“我要订货”页面banner展示，只能用上传图文消息内的图片获取URL--微信开放文档接口生成的链接，选填 business_msg_id: 自定义的消息id（选填，string类型，长度<20，建议英文或数字） |
| to_user_list | 门店负责人openid列表 | 门店负责人openid列表，最多一次发送200个openid |
注：对于keyword.DATA等”模板消息参数值内容限制说明“参见该链接：模板消息--微信开放文档
请求示例：
{
"type": 8,
"content": "{
\"content\":\"东鹏特饮250ml*10箱\",
\"amount\":\"¥200\",
\"delivery\":\"怡亚通\",
\"path\":\"pages/xxxxx\",
\"img_url\":\"xxxxx\",
\"business_msg_id\":\"eg123456\"
}",
"to_user_list":[
"xxxxxxxxxxxxxx"
]
}
返回示例：
{
"errcode": 0,
"errmsg": "OK"
}
# 门店订单派送通知
发送频次：（不限下发次数）
| 参数 | 说明 | 备注 |
|---|---|---|
| type | 消息类型 | 门店订单派送通知，填9 |
| content | 消息内容的json字符串 | content内的各个字段含义： content：订单内容 keyword.DATA delivery：配送商 keyword.DATA deliveryman：配送员姓名 keyword.DATA phone：配送员电话 keyword.DATA path：模板消息的跳转路径（只能跳转到当前调用api的小程序内路径，这里填小程序内的path即可。选填，默认跳转首页） img_url：小程序商家助手菜单栏“我要订货”页面banner展示，只能用上传图文消息内的图片获取URL--微信开放文档接口生成的链接，选填 business_msg_id: 自定义的消息id（选填，string类型，长度<20，建议英文或数字） |
| to_user_list | 门店负责人openid列表 | 门店负责人openid列表，最多一次发送200个openid |
注：对于keyword.DATA等”模板消息参数值内容限制说明“参见该链接：模板消息--微信开放文档
请求示例：
{
"type": 9,
"content": "{
\"content\":\"东鹏特饮250ml*10箱\",
\"delivery\":\"怡亚通\",
\"deliveryman\":\"小林\",
\"phone\":\"13212345678\",
\"path\":\"pages/xxxxx\",
\"img_url\":\"xxxxx\",
\"business_msg_id\":\"eg123456\"
}",
"to_user_list":[
"xxxxxxxxxxxxxx"
]
}
返回示例：
{
"errcode": 0,
"errmsg": "OK"
}
# 门店认证进度通知
发送频次：（不限下发次数）
| 参数 | 说明 | 备注 |
|---|---|---|
| type | 消息类型 | 门店认证进度通知，填10 |
| content | 消息内容的json字符串 | content内的各个字段含义： content：当前进展 keyword.DATA name：门店名称 keyword.DATA date：申请时间 keyword.DATA tips：提示 keyword.DATA path：模板消息的跳转路径（只能跳转到当前调用api的小程序内路径，这里填小程序内的path即可。选填，默认跳转首页） img_url：小程序商家助手菜单栏“我要订货”页面banner展示，只能用上传图文消息内的图片获取URL--微信开放文档接口生成的链接，选填 business_msg_id: 自定义的消息id（选填，string类型，长度<20，建议英文或数字） |
| to_user_list | 门店负责人openid列表 | 门店负责人openid列表，最多一次发送200个openid |
注：对于keyword.DATA等”模板消息参数值内容限制说明“参见该链接：模板消息--微信开放文档
请求示例：
{
"type": 10,
"content": "{
\"content\":\"待验证法人信息\",
\"name\":\"高高兴兴小卖部\",
\"date\":\"2022年5月21日17:20\",
\"tips\":\"完成门店认证，可获得优惠券\",
\"path\":\"pages/xxxxx\",
\"img_url\":\"xxxxx\",
\"business_msg_id\":\"eg123456\"
}",
"to_user_list":[
"xxxxxxxxxxxxxx"
]
}
返回示例：
{
"errcode": 0,
"errmsg": "OK"
}
# 门店订货活动通知
发送频次： 单门店可被发送上限：8次/月
| 参数 | 说明 | 备注 |
|---|---|---|
| type | 消息类型 | 门店订货活动通知，填11 |
| content | 消息内容的json字符串 | content内的各个字段含义： topic：活动主题 thing.DATA goods：活动商品 thing.DATA goods：活动商品 thing.DATA date：活动时间 time.DATA path：模板消息的跳转路径（只能跳转到当前调用api的小程序内路径，这里填小程序内的path即可。选填，默认跳转首页） img_url：小程序商家助手菜单栏“我要订货”页面banner展示，只能用上传图文消息内的图片获取URL--微信开放文档接口生成的链接，选填 business_msg_id: 自定义的消息id（选填，string类型，长度<20，建议英文或数字） |
| to_user_list | 门店负责人openid列表 | 门店负责人openid列表，最多一次发送200个openid |
注：对于thing.DATA等”模板消息参数值内容限制说明“参见该链接：模板消息--微信开放文档
请求示例：
{
"type": 11,
"content": "{
\"topic\":\"蒙牛特仑苏专场日\",
\"goods\":\"特仑苏沙漠有机纯牛奶250ml*10包\",
\"content\":\"订货满10箱送1箱\",
\"date\":\"2022/12/1～2023/1/1\",
\"path\":\"pages/xxxxx\",
\"img_url\":\"xxxxx\",
\"business_msg_id\":\"eg123456\"
}",
"to_user_list":[
"xxxxxxxxxxxxxx"
]
}
返回示例：
{
"errcode": 0,
"errmsg": "OK"
}
# 门店陈列任务通知
发送频次： 单门店可被发送上限：4次/月
| 参数 | 说明 | 备注 |
|---|---|---|
| type | 消息类型 | 门店陈列任务通知，填12 |
| content | 消息内容的json字符串 | content内的各个字段含义： name：任务名称 thing.DATA content：任务内容 thing.DATA reward：任务奖励 thing.DATA date：任务时间 time.DATA path：模板消息的跳转路径（只能跳转到当前调用api的小程序内路径，这里填小程序内的path即可。选填，默认跳转首页） img_url：小程序商家助手菜单栏“我要订货”页面banner展示，只能用上传图文消息内的图片获取URL--微信开放文档接口生成的链接，选填 business_msg_id: 自定义的消息id（选填，string类型，长度<20，建议英文或数字） |
| to_user_list | 门店负责人openid列表 | 门店负责人openid列表，最多一次发送200个openid |
注：对于thing.DATA等”模板消息参数值内容限制说明“参见该链接：模板消息--微信开放文档
请求示例：
{
"type": 12,
"content": "{
\"name\":\"可口可乐冰柜陈列任务\",
\"content\":\"连续一周正面拍照通电可口可乐冰柜\",
\"reward\":\"完成任务可得10元订货券\",
\"date\":\"2022/12/1～2023/1/1\",
\"path\":\"pages/xxxxx\",
\"img_url\":\"xxxxx\",
\"business_msg_id\":\"eg123456\"
}",
"to_user_list":[
"xxxxxxxxxxxxxx"
]
}
返回示例：
{
"errcode": 0,
"errmsg": "OK"
}
# 门店营销任务通知
发送频次： 单门店可被发送上限：4次/月
| 参数 | 说明 | 备注 |
|---|---|---|
| type | 消息类型 | 门店营销任务通知，填13 |
| content | 消息内容的json字符串 | content内的各个字段含义： name：任务名称 thing.DATA content：任务内容 thing.DATA reward：任务奖励 thing.DATA date：任务时间 time.DATA path：模板消息的跳转路径（只能跳转到当前调用api的小程序内路径，这里填小程序内的path即可。选填，默认跳转首页） img_url：小程序商家助手菜单栏“我要订货”页面banner展示，只能用上传图文消息内的图片获取URL--微信开放文档接口生成的链接，选填 business_msg_id: 自定义的消息id（选填，string类型，长度<20，建议英文或数字） |
| to_user_list | 门店负责人openid列表 | 门店负责人openid列表，最多一次发送200个openid |
注：对于thing.DATA等”模板消息参数值内容限制说明“参见该链接：模板消息--微信开放文档
请求示例：
{
"type": 13,
"content": "{
\"name\":\"东鹏开箱扫码任务\",
\"content\":\"开箱扫箱内码得东币\",
\"reward\":\"累积10次可得3元返货券\",
\"date\":\"2022/12/1～2023/1/1\",
\"path\":\"pages/xxxxx\",
\"img_url\":\"xxxxx\",
\"business_msg_id\":\"eg123456\"
}",
"to_user_list":[
"xxxxxxxxxxxxxx"
]
}
返回示例：
{
"errcode": 0,
"errmsg": "OK"
}
# 门店任务进展通知
发送频次： 单门店可被发送上限：1次/日
| 参数 | 说明 | 备注 |
|---|---|---|
| type | 消息类型 | 门店任务进展通知，填14 |
| content | 消息内容的json字符串 | content内的各个字段含义： topic：任务主题 thing.DATA progress：当前进展 thing.DATA content：完成内容 thing.DATA date：统计周期 time.DATA path：模板消息的跳转路径（只能跳转到当前调用api的小程序内路径，这里填小程序内的path即可。选填，默认跳转首页） img_url：小程序商家助手菜单栏“我要订货”页面banner展示，只能用上传图文消息内的图片获取URL--微信开放文档接口生成的链接，选填 business_msg_id: 自定义的消息id（选填，string类型，长度<20，建议英文或数字） |
| to_user_list | 门店负责人openid列表 | 门店负责人openid列表，最多一次发送200个openid |
注：对于thing.DATA等”模板消息参数值内容限制说明“参见该链接：模板消息--微信开放文档
请求示例：
{
"type": 14,
"content": "{
\"topic\":\"1元乐享商户扫任务\",
\"progress\":\"获得150东币\",
\"content\":\"扫码上架3次90分，开箱2次40分\",
\"date\":\"2022/12/1～2023/1/1\",
\"path\":\"pages/xxxxx\",
\"img_url\":\"xxxxx\",
\"business_msg_id\":\"eg123456\"
}",
"to_user_list":[
"xxxxxxxxxxxxxx"
]
}
返回示例：
{
"errcode": 0,
"errmsg": "OK"
}
# 优惠券到期提醒
发送频次： 单门店可被发送上限：4次/月
| 参数 | 说明 | 备注 |
|---|---|---|
| type | 消息类型 | 优惠券到期提醒，填15 |
| content | 消息内容的json字符串 | content内的各个字段含义： topic：到期主题 thing.DATA content：到期内容 thing.DATA date：到期时间 time.DATA path：模板消息的跳转路径（只能跳转到当前调用api的小程序内路径，这里填小程序内的path即可。选填，默认跳转首页） img_url：小程序商家助手菜单栏“我要订货”页面banner展示，只能用上传图文消息内的图片获取URL--微信开放文档接口生成的链接，选填 business_msg_id: 自定义的消息id（选填，string类型，长度<20，建议英文或数字） |
| to_user_list | 门店负责人openid列表 | 门店负责人openid列表，最多一次发送200个openid |
注：对于thing.DATA等”模板消息参数值内容限制说明“参见该链接：模板消息--微信开放文档
请求示例：
{
"type": 15,
"content": "{
\"topic\":\"立白订货券1日后到期\",
\"content\":\"满1000减50”订货券两张\",
\"date\":\"2022/12/1 23:59\",
\"path\":\"pages/xxxxx\",
\"img_url\":\"xxxxx\",
\"business_msg_id\":\"eg123456\"
}",
"to_user_list":[
"xxxxxxxxxxxxxx"
]
}
返回示例：
{
"errcode": 0,
"errmsg": "OK"
}
# 积分到期提醒
发送频次： 单门店可被发送上限：4次/月
| 参数 | 说明 | 备注 |
|---|---|---|
| type | 消息类型 | 积分到期提醒，填16 |
| content | 消息内容的json字符串 | content内的各个字段含义： topic：到期主题 thing.DATA content：到期内容 thing.DATA date：到期时间 time.DATA path：模板消息的跳转路径（只能跳转到当前调用api的小程序内路径，这里填小程序内的path即可。选填，默认跳转首页） img_url：小程序商家助手菜单栏“我要订货”页面banner展示，只能用上传图文消息内的图片获取URL--微信开放文档接口生成的链接，选填 business_msg_id: 自定义的消息id（选填，string类型，长度<20，建议英文或数字） |
| to_user_list | 门店负责人openid列表 | 门店负责人openid列表，最多一次发送200个openid |
注：对于thing.DATA等”模板消息参数值内容限制说明“参见该链接：模板消息--微信开放文档
请求示例：
{
"type": 16,
"content": "{
\"topic\":\"订货积分即将到期\",
\"content\":\"你有500订货积分即将到期\",
\"date\":\"2022/12/1 23:59\",
\"path\":\"pages/xxxxx\",
\"img_url\":\"xxxxx\",
\"business_msg_id\":\"eg123456\"
}",
"to_user_list":[
"xxxxxxxxxxxxxx"
]
}
返回示例：
{
"errcode": 0,
"errmsg": "OK"
}
# 兑换券到期提醒
发送频次： 单门店可被发送上限：4次/月
| 参数 | 说明 | 备注 |
|---|---|---|
| type | 消息类型 | 兑换券到期提醒，填17 |
| content | 消息内容的json字符串 | content内的各个字段含义： topic：到期主题 thing.DATA content：到期内容 thing.DATA date：到期时间 time.DATA path：模板消息的跳转路径（只能跳转到当前调用api的小程序内路径，这里填小程序内的path即可。选填，默认跳转首页） img_url：小程序商家助手菜单栏“我要订货”页面banner展示，只能用上传图文消息内的图片获取URL--微信开放文档接口生成的链接，选填 business_msg_id: 自定义的消息id（选填，string类型，长度<20，建议英文或数字） |
| to_user_list | 门店负责人openid列表 | 门店负责人openid列表，最多一次发送200个openid |
注：对于thing.DATA等”模板消息参数值内容限制说明“参见该链接：模板消息--微信开放文档
请求示例：
{
"type": 17,
"content": "{
\"topic\":\"兑换券即将到期\",
\"content\":\"你有12箱特仑苏兑换券即将到期\",
\"date\":\"2022/12/1 23:59\",
\"path\":\"pages/xxxxx\",
\"img_url\":\"xxxxx\",
\"business_msg_id\":\"eg123456\"
}",
"to_user_list":[
"xxxxxxxxxxxxxx"
]
}
返回示例：
{
"errcode": 0,
"errmsg": "OK"
}
# 门店调研通知
发送频次： 单门店可被发送上限：4次/月
| 参数 | 说明 | 备注 |
|---|---|---|
| type | 消息类型 | 门店调研通知，填18 |
| content | 消息内容的json字符串 | content内的各个字段含义： topic：调研主题 thing.DATA content：调研内容 thing.DATA date：截止时间 time.DATA path：模板消息的跳转路径（只能跳转到当前调用api的小程序内路径，这里填小程序内的path即可。选填，默认跳转首页） img_url：小程序商家助手菜单栏“我要订货”页面banner展示，只能用上传图文消息内的图片获取URL--微信开放文档接口生成的链接，选填 business_msg_id: 自定义的消息id（选填，string类型，长度<20，建议英文或数字） |
| to_user_list | 门店负责人openid列表 | 门店负责人openid列表，最多一次发送200个openid |
注：对于thing.DATA等”模板消息参数值内容限制说明“参见该链接：模板消息--微信开放文档
请求示例：
{
"type": 18,
"content": "{
\"topic\":\"乐事薯片口味调研\",
\"content\":\"完成问卷即可获得10元订货券（限新品）\",
\"date\":\"2023/1/30 23:59\",
\"path\":\"pages/xxxxx\",
\"img_url\":\"xxxxx\",
\"business_msg_id\":\"eg123456\"
}",
"to_user_list":[
"xxxxxxxxxxxxxx"
]
}
返回示例：
{
"errcode": 0,
"errmsg": "OK"
}
# 2.3 错误码说明
| errcode | 错误说明 |
|---|---|
| 9403000 | 消息类型错误! |
| 9403001 | 消息字段的内容过长! |
| 9403002 | 消息字段的内容违规! |
| 9403003 | 发送的微信号太多! |
| 40003 | 存在错误的openid! |
# 2.4 消息效果数据api
调用方式
HTTPS 调用
POST https://api.weixin.qq.com/wxa/business/getretailmessagelist?access_token=ACCESS_TOKEN
请求参数
| 属性 | 类型 | 必填 | 说明 |
|---|---|---|---|
| access_token | string | 是 | 接口调用凭证，该参数为 URL 参数，非 Body 参数。使用 getAccessToken 或者 authorizer_access_token |
| begin_date | string | 是 | 开始时间，格式为“xxxx-yy-zz”的字符串，例如：“2024-08-01” |
| end_date | string | 是 | 结束时间，格式为“xxxx-yy-zz”的字符串，例如：“2024-08-10” |
| start | number | 是 | 分页起始位置，从0开始计数，用于分页查询，默认值为0 |
| offset | number | 是 | 每页返回的数据条数上限，最大值为1000，默认值为20 |
返回参数
| 属性 | 类型 | 说明 |
|---|---|---|
| errcode | number | 错误码 |
| errmsg | string | 错误原因 |
| total_num | number | 查询到数据总数 |
| data_line | array<json> | 数据列表: { msg_id: 消息id； msg_type: 消息类型 date: 消息日期； send_uv: 发送人数； entry_uv: 进入人数； date: 消息日期； msg_time: 消息发送时间； business_msg_id: 自定义msg_id； } |
调用示例
请求数据示例
{
"start": 0,
"offset": 100,
"begin_date": "2024-08-10",
"end_date": "2024-08-15"
}
返回数据示例
{
"errcode": 0,
"errmsg": "ok",
"total_num": 2,
"data_line": [
{
"msg_id": 2,
"msg_type": 11,
"date": "2024-08-13",
"msg_time": "2024-08-13 20:55:37",
"send_uv": 1,
"entry_uv": 1,
"business_msg_id": "XXX"
},
{
"msg_id": 1,
"msg_type": 11,
"date": "2024-08-13",
"msg_time": "2024-08-13 20:01:15",
"send_uv": 2,
"entry_uv": 1,
"business_msg_id": "XXX"
}
]
}
常见错误码
| errcode | 说明 |
|---|---|
| 0 | 成功 |
| -1 | 系统错误 |
| 40079 | 日期格式错误 |
| 45165 | offset格式错误或超过最大限制 |
# 3. B2b支付
使用本支付服务，核心包括三个步骤：
3.1、申请微信支付商户号（页面端&接口）
登录mp.weixin.qq.com，进入小程序后台页面，在"门店助手-支付管理"栏目，申请微信支付商户号。也可以通过接口方式进行申请。
3.2、报名技术服务费优惠活动（页面端&接口）
开通成功的商户号，技术服务费费率默认为标准费率。可报名技术服务费优惠活动，获得更低的活动费率。
若小程序为服务商代开发模式（代开发权限集 18 or B2b门店助手权限集158，授权给到第三方平台），则需要由服务商代为报名。
3.3、支付与退款（接口）
对接接口，完成下单支付与退款操作
3.4、查看账单（页面端&接口）
登录mp.weixin.qq.com，进入小程序后台页面，在"门店助手-支付管理"栏目，可查看交易账单，以及操作提现。也可以通过接口的方式获取交易账单与资金账单。
3.5、提现（页面端&接口）
支持手动提现或者设置自动提现。
# 3.1 申请微信支付商户号
# 1、提交商户相关资料
# 页面端方式：
登录mp.weixin.qq.com，进入小程序后台页面，在"门店助手-支付管理"栏目，申请微信支付商户号。填写企业的营业执照，提现账户及支付管理员。
# 接口端方式：商户号进件 API
可以通过 api 方式进行商户号的进件。
接口说明
请求URL：https://api.weixin.qq.com/retail/B2b/retailregistermch?access_token=ACCESS_TOKEN
请求方式：POST
请求参数
| 参数名 | 类型 | 内容 | 描述 | 必填 |
|---|---|---|---|---|
| id_doc_type_num | uint32 | 法人证件类型 | 0-默认即大陆身份证，1-大陆身份证，2-其他国家或地区居民护照，3-中国香港居民来往内地通行证，4-中国澳门居民–来往内地通行证，5-中国台湾居民–来往大陆通行证 | 是 |
| id_card_info | JSON | 经营者/法人身份证信息 | - id_card_copy: string, 身份证人像面照片id, 通过上传商户资料api获取 - id_card_national: string, 身份证国徽面照片id, 通过上传商户资料api获取 - id_card_name: string, 身份证姓名 - id_card_number: string, 身份证号码 - id_card_valid_time: string, 身份证有效期限, 格式如"2026-06-06" - id_card_address: string, 身份证地址 - id_card_valid_time_begin: string, 身份证有效期开始日期, 格式如"2026-06-06" | 当id_doc_type_num为0和1时必填 |
| id_doc_info | JSON | 经营者/法人其他类型证件信息 | - id_doc_name：string，证件姓名 - id_doc_number: string，证件号码 - id_doc_copy：string，证件正面照片，通过上传商户资料 api 获取 - doc_period_end: string，证件结束日期，格式如"2022-06-06" - doc_period_begin: string，证件有效期开始时间，格式如"2022-06-06" - id_doc_address: string，证件居住地址 - id_doc_copy_back: string，证件反面照片，通过上传商户资料 api 获取 | 当id_doc_type_num不为0和1时必填 |
| account_info | JSON | 结算银行账户 | - bank_account_type: string，账户类型，若主体为企业/党政、机关及事业单位/其他组织，可填"74"，表示对公账户；若主体为"小微/个人卖家"，可填"75"，表示对私账户；若主体为个体工商户，可填"74"或"75" - account_bank: string, 开户银行，比如"工商银行" - account_name: string，开户名称 - bank_address_code: string，开户银行省市编码，例如"110000" - bank_branch_id: string，开户银行联行号，17 家直连银行无需填写，如为其他银行，开户银行全称（含支行）和开户银行联行号二选一 - bank_name: string，开户银行全称 - account_number: string，银行帐号 | 是 |
| contact_info | JSON | 超级管理员信息 | - contact_type: string, 主体为"小微/个人卖家"，可填"65"; 主体为"个体工商户/企业/党政、机关及事业单位/其他组织"，可填"65"表示经营者/法人，或者"66"表示负责人。 - contact_name: string，超级管理员姓名 - contact_id_doc_type：string，超级管理员证件类型 当超级管理员类型是经办人时，请上传超级管理员证件类型。 // 中国大陆居民-身份证 "IDENTIFICATION_TYPE_MAINLAND_IDCARD" // 其他国家或地区居民-护照 "IDENTIFICATION_TYPE_OVERSEA_PASSPORT" // 中国香港居民–来往内地通行证 "IDENTIFICATION_TYPE_HONGKONG" // 中国澳门居民–来往内地通行证 "IDENTIFICATION_TYPE_MACAO" // 中国台湾居民–来往大陆通行证 "IDENTIFICATION_TYPE_TAIWAN" - contact_id_card_number：string，超级管理员身份证件号码 - contact_id_doc_copy：string，超级管理员证件正面照片id，当超级管理员类型是经办人时，请上传超级管理员证件的正面照片。 - contact_id_doc_copy_back: string,超级管理员证件反面照片,当超级管理员类型是经办人时，请上传超级管理员证件的正面照片。 - contact_id_doc_period_begin: string,超级管理员证件有效期开始时间 当超级管理员类型是经办人时，请上传证件有效期开始时间。 - contact_id_doc_period_end: string, 级管理员证件有效期结束时间 当超级管理员类型是经办人时，请上传证件有效期结束时间。 - business_authorization_letter: string，业务办理授权函。1、当超级管理员类型是经办人时，请上传业务办理授权函。2、请参照示例图打印业务办理授权函，全部信息需打印，不支持手写商户信息，并加盖公章。 - mobile_phone: string, 超级管理员手机, - contact_email: string, 超级管理员邮箱,主体类型为"小微商户/个人卖家"可选填，其他主体需必填。 | 是 |
| business_license | JSON | 营业执照 | - business_license_copy: string, 证件扫描件图片id，可通过上传商户资料 api 获取 - business_license_number: string, 证件注册号 - merchant_name: string, 商户名称 - legal_person: string, 经营者/法定代表人姓名 - company_address: string, 注册地址，主体为"党政、机关及事业单位/其他组织"时必填，请填写登记证书的注册地址。 - business_time: string, 营业期限，主体为"党政、机关及事业单位/其他组织"时必填。 - cert_type: string, 1、主体为"政府机关/事业单位/社会组织"时，请上传登记证书类型。2、主体为"个体工商户/企业"时，不填。当主体为事业单位时，填枚举值："CERTIFICATE_TYPE_2388", 表示事业单位法人证书；当主体为政府机关，填枚举值："CERTIFICATE_TYPE_2389"，表示统一社会信用代码证书 | 是 |
| merchant_shortname | string | 商户名缩写 | - | 1、主体为"小微/个人卖家"时，不填。 2、主体为"个体工商户/企业"时，请上传营业执照。 3、主体为"党政、机关及事业单位/其他组织"时，请上传登记证书。 |
| organization_type | uint32 | 主体类型 | 个人-0，企业-1 | 必填 |
| qualification | JSON | 行业特殊资质资料 | - qualification_type: 行业特殊资质类型，如"速送", 见：https://kf.qq.com/faq/220228qEfuAz220228bMFji6.html - qualifications: 行业特殊资料, 字符串数组构成的字符串，示例值:"["jTpGmxUX3FBWVQ5NJInE4d2I6_H7I4"]" | 需要上传行业特殊资料时必填 |
返回参数
| 参数名 | 类型 | 内容 | 描述 |
|---|---|---|---|
| errcode | int32 | 错误码 | - |
| errmsg | string | 错误信息 | - |
| order_no | string | 进件申请单号 | 可用于查询进件状态 |
请求示例
{
"id_doc_type_num": 1,
"id_card_info": {
"id_card_copy": "V1_xxxxxxx",
"id_card_national": "V1_xxxxxx",
"id_card_name": "小明",
"id_card_number": "440000199001011111",
"id_card_valid_time": "2041-01-01",
"id_card_address": "北京市朝阳区等等等",
"id_card_valid_time_begin": "2021-01-01"
},
"account_info": {
"bank_account_type": "74",
"account_bank": "招商银行",
"account_name": "北京食品有限公司",
"bank_address_code": "123",
"account_number": "123"
},
"contact_info": {
"contact_type": "65",
"contact_name": "小明",
"contact_id_card_number": "440000199001011111",
"mobile_phone": "12345678911",
"contact_email": "test@qq.com"
},
"business_license": {
"business_license_copy": "V1_xxxx",
"business_license_number": "ABC123",
"merchant_name": "北京食品有限公司",
"legal_person": "小明"
},
"merchant_shortname": "北京食品",
"organization_type": 1
}
返回示例
{
"errcode": 0,
"errmsg": "OK",
"order_no": "regorder123"
}
错误码
| errcorde | errmsg |
|---|---|
| 90000 | 商户主体已经处于进件中 |
| 90001 | 主体类型不符要求 |
| 90003 | 提交频繁 |
| 90004 | 证件类型不符 |
| 90005 | 该商户主体进件数目达到上限 |
| 9403200 | id_doc_type_num字段超出范围 |
# 接口端方式：上传商户图片 API
可以通过api 上传资料获取图片 id，进件时填充图片 id
接口说明
请求URL：https://api.weixin.qq.com/retail/B2b/retailuploadmchfile?access_token=ACCESS_TOKEN
请求方式：POST
请求参数
| 参数名 | 类型 | 内容 | 描述 | 必填 |
|---|---|---|---|---|
| file_name | string | 文件名 | - | 必填 |
| file | bytes | 文件二进制流 | - | 必填 |
返回参数
| 参数名 | 类型 | 内容 | 描述 |
|---|---|---|---|
| errcode | int32 | 错误码 | - |
| errmsg | string | 错误信息 | - |
| file_id | string | 文件 id | - |
# 2、查询商户号开通状态
# 页面端方式：
登录mp.weixin.qq.com，进入小程序后台页面，在"门店助手-支付管理"栏目，可随时查看最新的申请进度。
# 接口端方式：查询商户号进件状态API
可以通过api方式查询商户号进件订单（包含状态信息等）
接口说明
请求URL：https://api.weixin.qq.com/retail/B2b/retailgetmchorder?access_token=ACCESS_TOKEN
请求方式：POST
请求参数
| 参数名 | 类型 | 内容 | 描述 | 必填 |
|---|---|---|---|---|
| out_registration_id | string | 订单号 | 某个特定的进件订单号 | 否，不填则表示拉出当前小程序的所有进件单 |
| page_index | uint32 | 分页拉取偏移 | - | 否 |
| page_size | uint32 | 分页拉取总量限制 | - | 否 |
返回参数
| 参数名 | 类型 | 内容 | 描述 |
|---|---|---|---|
| errcode | int32 | 错误码 | - |
| errmsg | string | 错误信息 | - |
| list | array<JSON> | 订单列表 | status: 0-初始化 1-资料校验中 2-待账户验证 3-审核中 4-已驳回 5-待签约 6-完成 6-已冻结 8-已作废 9-完成前平台额外准备 inner_resp:定义见下表 |
| total | uint32 | 返回订单总数 | - |
| 返回参数 | 参数名 | 变量 | 类型[长度限制] | 必填 | 描述 | 枚举值 |
|---|---|---|---|---|---|---|
| 申请状态 | applyment_state | string[1,32] | 是 | 申请状态描述 | CHECKING: 资料校验中 ACCOUNT_NEED_VERIFY: 待账户验证 AUDITING: 审核中 REJECTED: 已驳回 NEED_SIGN: 待签约 FINISH: 完成 FROZEN: 已冻结 CANCELED: 已作废 | 示例值: FINISH |
| 申请状态描述 | applyment_state_desc | string[1,1024] | 是 | 申请状态描述 | 示例值: "完成" | |
| 签约状态 | sign_state | string[1,16] | 否 | 签约状态描述 | 1. UNSIGNED: 未签约。 该状态下，电商平台可查询获取签约链接，引导二级商户的超级管理员完成签约； 2. SIGNED: 已签约。 指二级商户的超级管理员已完成签约。注意：若申请单被驳回，商户修改了商户主体名称、法人名称、超级管理员信息、主体类型等信息，则需要重新签约。 3. NOT_SIGNABLE: 不可签约。 该状态下，暂不支持超级管理员签约。一般为申请单处于已驳回、已冻结、机器校验中状态，无法签约。 | 示例值: SIGNED |
| 签约链接 | sign_url | string[1,256] | 否 | 签约链接 | 1. 当申请状态为 NEED_SIGN 或 签约状态为 UNSIGNED 时返回，该链接为永久有效； 2. 申请单中的超级管理员，需用已实名认证的微信扫码打开，完成签约。 | 示例值: https://pay.weixin.qq.com/public/apply4ec_sign/s?applymentId=2000002126198476&sign=b207b673049a32c858f3aa0bd7d27c7ec |
| 电商平台二级商户号 | sub_mchid | string[1,32] | 否 | 电商平台二级商户号 | 当申请状态为 NEED_SIGN 或 FINISH 时才返回。 | 示例值: 1542488631 |
| +汇款账户验证信息 | account_validation | object | 否 | 汇款账户验证信息 | 当申请状态为 ACCOUNT_NEED_VERIFY 时有返回，可根据指引汇款，完成账户验证。 | |
| +驳回原因详情 | audit_detail | array | 否 | 驳回原因详情 | 各项资料的审核情况。当申请状态为 REJECTED 或 FROZEN 时才返回。 | |
| 法人验证链接 | legal_validation_url | string[1,256] | 否 | 法人验证链接 | 1. 当申请状态为 ACCOUNT_NEED_VERIFY，且通过系统校验的申请单，将返回链接。 2. 建议将链接转为二维码展示，让商户法人用微信扫码打开，完成账户验证。 注：商户申请单进入审核状态后，微信侧会校验法人证件号码是否跟营业执照匹配，若匹配，返回该字段；若不匹配，不支持法人扫码验证，不返回该字段。 | 示例值: http://pay.weixin.qq.com/public/apply4ec_sign/s?applymentId=2000002126198476&sign=b207b673049a32c858f3aa0bd7d27c7ec |
# 3、进行账户验证（若支付管理员为公司法人，无该步骤）
若支付管理员不是法人，则需进行账户验证，可以选择以下任一方式。
# 4、资料审核与账户状态查询
完成商户资料提交及账户验证后，将进入平台审核环节，审核一般需要1-7个工作日，你可以随时进入页面或通过查询 API查看最新审核状态。
# 5、签约
平台审核通过后，进入最终商户号开通签约环节，请超级管理员根据指引扫码完成签约。
完成签约后，将进入"商户号开通中"状态，平台将为你开通商户号，稍后片刻即可完成最终开通。当状态变成"已开通"后，即可通过该商户号使用本支付服务。
# 6、完成商户号与小程序的关联
商户号完成开通后，需根据指引进行相关操作，确保"与小程序关联状态"为"已关联"，商户号方可在小程序中成功发起支付！
1）当"与小程序关联状态"为"待商户号超管同意"时
请商户号超管前往"微信支付商家助手"公众号按照收到的"创建经营场景申请进展通知"，或者pc 登录商户平台pay.weixin.qq.com按照站内信通知，进行相关操作：
【特别说明】因平台运营规范要求，实物交易类小程序后续均需要接入订单发货管理功能，其中部分小程序已经要求接入。
对于要求接入的小程序，商户号超管进行创建经营场景确认的时候，需按照页面指引进行相关确认授权。
确认授权后，正常交易情况下，交易都会 T+0自动结算，无需用户确认收货，无需对接订单发货管理接口。仅当交易出现违规时，平台会进行介入。请放心操作。
2）当"与小程序关联状态"为"待小程序超管同意"时
请小程序超管pc 登录小程序后台 mp.weixin.qq.com，前往【功能-微信支付】，针对以下两个待确认流程进行确认操作。
# 3.2 报名技术服务费优惠活动
# 页面端方式：
商户号开通成功后，即可操作报名。
# 接口端方式：
接口说明
请求 URL：https://api.weixin.qq.com/retail/B2b/setmchprofitrate?access_token=ACCESS_TOKEN
请求方式：POST
请求参数
| 参数名 | 类型 | 内容 | 描述 | 必填 |
|---|---|---|---|---|
| sub_mchid | string | 商户号 | - | 是 |
| profit_rate | uint32 | 费率 | 万分比，比如 40 指的是 0.40% | 是 |
返回参数
| 参数名 | 类型 | 内容 | 描述 |
|---|---|---|---|
| errcode | int32 | 错误码 | - |
| errmsg | string | 错误信息 | - |
请求示例
{
"sub_mchid": "123",
"profit_rate": 20,
}
返回示例
{"errcode":0, "errmsg":"OK"}
错误码
| errcode | errmsg |
|---|---|
| 11 | 缺少设置费率的权限 |
| 12 | 不在可以设置费率的时间范围内 |
| 13 | 费率只能下调 |
| 14 | 费率不在范围内调 |
# 3.3 支付与退款
# 1、签名详解
在基础库wx.requestCommonPayment会涉及用户态签名signature和支付签名paySig，在服务器API接口会涉及支付签名pay_sig，和小程序接口的paySig签名方式一致，都遵循本签名详解。
支付签名
签名算法伪代码为
signature = to_hex(hmac_sha256(sessionKey,signData))
| 参数 | wxAPI | 服务器API |
|---|---|---|
| appKey | 可通过小程序MP查看：门店助手 -> 支付管理 -> 商户号管理查看详情->基本配置中的沙箱AppKey和现网AppKey。注意：记得根据env值选择不同AppKey，env = 0对应现网AppKey，env = 1对应沙箱AppKey | 获得方式相同，服务器API只用现网AppKey，不区分环境 |
| signData | 基础库的signData字段 | api的post body |
| uri | requestCommonPayment | 举例：对于https://api.weixin.qq.com/retail/B2b/getorder 来说，uri = /retail/B2b/getorder |
用户态签名
签名算法伪代码为：
signature = to_hex(hmac_sha256(sessionKey,signData))
| 参数 | wxAPI | 服务器API |
|---|---|---|
| sessionKey | session_key | 获得方式相同，服务器API暂不需要 |
| signData | 基础库的signData字段 | api的post body |
参考的python脚本
以调用getorder为例，签名计算如下：
#!/usr/bin/python
# -*- coding: utf-8 -*-
""" pay_sig签名算法计算示例 """
import hmac
import hashlib
import json
import time
def calc_pay_sig(uri, post_body, appkey):
""" pay_sig签名算法
Args:
uri - 当前请求的API的uri部分，不带query_string 例如：/retail/B2b/getorder
post_body - http POST的数据包体
appkey - 对应环境的AppKey
Returns:
支付请求签名pay_sig
"""
need_sign_msg = uri + '&' + post_body
pay_sig = hmac.new(key = appkey.encode('utf-8'), msg = need_sign_msg.encode('utf-8'),
digestmod=hashlib.sha256).hexdigest()
return pay_sig
def calc_signature(post_body, session_key):
""" 用户登录态signature签名算法
Args:
post_body - http POST的数据包体
session_key - 当前用户有效的session_key，参考auth.code2Session接口
Returns:
用户登录态签名signature
"""
need_sign_msg = post_body
signature = hmac.new(key = session_key.encode('utf-8'), msg = need_sign_msg.encode('utf-8'),
digestmod=hashlib.sha256).hexdigest()
return signature
# uri，切记不可带参数，即去掉"?"及后面的部分
# 如果是基础库的wx.requestCommonPayment，uri固定为requestCommonPayment
uri = '/retail/B2b/getorder'
# 此处appkey为假设值，实际使用应根据支付环境(env参数)替换为对应的AppKey
appkey = "12345"
# 注意：JSON数据序列化结果，不同语言/版本结果可能不同
# 所以示例为了保证稳定性，直接用其中一个序列化的版本
# 实际使用时只需要保证，参与签名的post_body和真正发起http请求的一致即可
"""
# 不同接口要求的Post Body参数不一样，此处以getorder接口为例(和uri对应）
post_body = json.dumps({
"mchid": "1230000109",
"out_trade_no": "1217752501201407033233368018"
})
"""
post_body = '{"mchid": "1230000109","out_trade_no": "1217752501201407033233368018"}'
# step1. pay_sig签名计算（支付请求签名算法）
pay_sig = calc_pay_sig(uri, post_body, appkey)
print("pay_sig:", pay_sig)
# 若实际请求返回pay_sig签名不对，根据以下步骤排查：
# 1. 确认算法：uri、post_body、appkey写死以上参数，确保你的签名算法和示例calc_pay_sig结果完全一致
# 2. 确认参数：
# - uri不可带参数（即"?"及后续部分全部舍去）
# - post_body必须和真正发起HTTP请求的post body完全一致
# - appkey必须是与请求中对应的环境匹配（env参数决定）
assert pay_sig == "2cb3e9fda4da9774f0c6f747bbf6c56e9045969d9921db7344fffdc945c1dc23"
# step2. signature签名计算（用户登录态签名算法）
# session_key需要为当前用户有效session_key（参考auth.code2Session接口获取）
# 此处写死方便复现算法
session_key = "9hAb/NEYUlkaMBEsmFgzig=="
signature = calc_signature(post_body, session_key)
print("signature:", signature)
assert signature == "47784191c740b0522d39d0a3926a19aa0e30c77975f689a9739c9553ffac2d9d"
# 2、下单
接口说明
小程序接口 wx.requestCommonPayment(Object object)
请求参数
| 属性 | 类型[长度限制] | 必填 | 描述 |
|---|---|---|---|
| signData | Object | 是 | 具体支付参数，详见signData，该参数以string传递。 示例值：'{"mchid":"1654806452","out_trade_no":"test1244","description":"测试测试","amount":{"order_amount":1,"currency":"CNY"},"attach":"test_attach","env":1}' |
| mode | string | 是 | 支付类型，不同mode的signData不同，B2b支付固定填retail_pay_goods 示例值：retail_pay_goods |
| paySig | string | 是 | 支付签名，详见签名详解 |
| signature | string | 是 | 用户态签名，详见签名详解 |
| success | function | 否 | 接口调用成功的回调函数 |
| fail | function | 否 | 接口调用失败的回调函数 |
| complete | function | 否 | 接口调用结束的回调函数（调用成功、失败都会执行） |
1) signData
| 参数名 | 变量 | 类型[长度限制] | 必填 | 描述 |
|---|---|---|---|---|
| 微信商户号 | mchid | string[1,32] | 是 | 由微信支付生成并下发的商户号。 示例值：1230000109 |
| 商户订单号 | out_trade_no | string[6,32] | 是 | 商户系统内部订单号，只能是数字、大小写字母_-*且在同一个商户号下唯一 示例值：1217752501201407033233368018 |
| 商品描述 | description | string[1,127] | 是 | 商品描述 示例值：Image形象店-深圳腾大-QQ公仔 |
| 订单金额 | amount | object | 是 | 订单金额信息，仅支持人民币，格式见Amount |
| 附加数据 | attach | string[1,128] | 否 | 附加数据，在查询API和支付通知中原样返回，可作为自定义参数使用，实际情况下只有支付完成状态才会返回该字段。 示例值：自定义数据 |
| 商品信息 | product_info | array | 否 | 订单详细商品信息，格式见ProductInfo |
| 配送方式 | delivery_type | uint32 | 否 | 配送方式，具体取值为： 1.同城配送 2.快递配送 3.门店自提 4.无需配送与提货 示例值：2 |
| 下单环境 | env | uint32 | 是 | 下单环境，具体取值为：0.生产环境 1.沙箱环境 示例值：0 |
2）Amount
| 参数名 | 变量 | 类型[长度限制] | 必填 | 描述 |
|---|---|---|---|---|
| 商品原总金额 | product_amount | int64 | 否 | 订单所有商品的原价总和，单位为分 示例值：1000 |
| 运费 | freight | int64 | 否 | 订单运费，单位为分 示例值：200 |
| 总优惠金额 | discount | int64 | 否 | 订单总计优惠金额，单位为分 示例值：500 |
| 其他费用 | other_fee | int64 | 否 | 订单其他费用总金额，单位为分 示例值：600 |
| 订单总金额 | order_amount | int64 | 是 | 订单总需支付金额，也即是真正下单总金额，单位为分 示例值：1300 |
| 货币类型 | currency | string | 否 | 货币类型，仅支持"CNY"。 示例值：CNY |
3）ProductInfo
| 参数名 | 变量 | 类型[长度限制] | 必填 | 描述 |
|---|---|---|---|---|
| 商品编号 | spu_id | string | 是 | 商户系统内该商品的spuid 示例值：spu123456 |
| 商品规格编号 | sku_id | string | 是 | 商户系统内该商品的skuid 示例值：sku123 |
| 商品标题 | title | string[1,60] | 是 | 商品标题 示例值：QQ长鹅 |
| 商详页小程序路径 | path | string | 是 | 商户商品详请页小程序路径 示例值：pages/index |
| 商品主图 | head_img | string | 是 | 商品主图的url，大小建议64*64 示例值：https://mp.weixin.qq.com/123 |
| 类目 | category | string | 是 | 商户侧该商品所属的类目 示例值：玩偶 |
| sku属性 | sku_attr | string | 是 | 商户系统内该商品的sku属性 示例值：50cm |
| 商品原价 | org_price | int32 | 是 | 该商品原价，单位为分 示例值：5000 |
| 商品售价 | sale_price | int32 | 是 | 该商品售价，单位为分 示例值：4000 |
| 商品数量 | quantity | int32 | 是 | 用户购买该商品的数量 示例值：5 |
请求示例
{
"signData": "{\"mchid\":\"1654806452\",\"out_trade_no\":\"test1244\",\"description\":\"测试测试\",\"amount\":{\"order_amount\":1,\"currency\":\"CNY\"},\"attach\":\"test_attach\",\"env\":1}",
"mode": "retail_pay_goods",
"paySig": "xxxxxxxxxx",
"signature": "xxxxxxxxxx"
}
返回参数
object.success 回调函数
| 属性 | 类型 | 说明 |
|---|---|---|
| errMsg | string | 调用成功信息 |
object.fail 回调函数
| 属性 | 类型 | 说明 |
|---|---|---|
| errMsg | string | 错误信息 |
| errCode | number | 错误码 |
错误码
| 错误码 | 说明 |
|---|---|
| 1000 | 系统错误 |
| 1022 | 参数json格式非法 |
| 702001 | 参数错误，具体原因见err_msg |
| 702002 | 用户态签名错误 |
| 702003 | 支付签名错误 |
| 702004 | mode不合法 |
| 702005 | out_trade_no重复，请更换新单号重试 |
| 702006 | 二级商户进件未完成 |
| 702008 | 正式版小程序只能用生产环境下单 |
# 3、支付通知
接口说明
通过消息推送功能发送给业务方服务器，业务方按照消息推送的要求回复，否则会认为通知失败。通知失败后会按照一定的策略重新发起通知，以尽可能通知到商户，但并不保证通知最终能成功。（通知重试频率为10s, 30s, 60s, 5min, 15min, 30min, 60m, 3h, 6h, 12h）
通知参数
| 参数名 | 变量 | 类型[长度限制] | 必填 | 描述 |
|---|---|---|---|---|
| 小程序原始ID | ToUserName | string | 是 | 小程序原始ID 示例值：gh_xxxxx |
| 事件消息openid | FromUserName | string | 是 | 微信官方的openid 示例值：oUpF8uMuAJO_M2pxb1Q9zNjWeS6o |
| 消息发送时间 | CreateTime | int64 | 是 | 消息发送时间戳 示例值：1698643478 |
| 消息类型 | MsgType | string | 是 | 消息类型，固定为event 示例值：event |
| 事件类型 | Event | string | 是 | 事件类型，固定为retail_pay_notify 示例值：retail_pay_notify |
| 小程序ID | appid | string[1,32] | 是 | 商户申请的小程序对应的appid 示例值：wx8888888888888888 |
| 微信商户号 | mchid | string[1,32] | 是 | 由微信支付生成并下发的商户号。 示例值：1230000109 |
| 商户订单号 | out_trade_no | string[6,32] | 是 | 商户系统内部订单号，只能是数字、大小写字母_-*且在同一个商户号下唯一 示例值：1217752501201407033233368018 |
| B2b支付订单号 | order_id | string[1,32] | 是 | B2b支付生成的订单号 示例值：o202307291423123564754773 |
| 订单状态 | pay_status | string[1,32] | 是 | 订单状态，枚举值 ORDER_INIT：订单初始化 ORDER_PRE_PAY：订单预下单成功，待支付 ORDER_PAY_SUCC：订单支付成功 ORDER_CLOSE：订单已关闭 ORDER_REFUND_PROCESSING：订单正在退款中 ORDER_REFUND：订单已有退款 示例值：ORDER_PAY_SUCC |
| 支付完成时间 | pay_time | string[1,32] | 否 | 支付完成时间，标准北京时间，时区为东八区，格式为yyyy-MM-dd HH:mm:ss 示例值：2023-07-20 17:04:28 |
| 附加数据 | attach | string[1,128] | 否 | 附加数据，在查询API和支付通知中原样返回，可作为自定义参数使用，实际情况下只有支付完成状态才会返回该字段。 示例值：自定义数据 |
| 支付者 | payer_openid | string[1,128] | 是 | 用户在直连商户appid下的唯一标识。 示例值：oUpF8uMuAJO_M2pxb1Q9zNjWeS6o |
| 订单金额 | amount | object | 否 | 订单金额信息，仅支持人民币，格式见Amount |
| 微信支付订单号 | wxpay_transaction_id | string[1,32] | 否 | 微信支付生成的订单号 示例值：2123191423123564754773 |
| 订单环境 | env | int32 | 是 | 订单环境 0：正式环境 1：沙箱环境 示例值：0 |
1) Amount
| 参数名 | 变量 | 类型[长度限制] | 必填 | 描述 |
|---|---|---|---|---|
| 订单总金额 | order_amount | int64 | 是 | 订单总需支付金额，也即是真正下单总金额，单位为分 示例值：1300 |
| 用户支付金额 | payer_amount | int64 | 是 | 用户支付金额，单位为分（指使用优惠券的情况下，这里等于总金额-优惠券金额，目前暂不支持优惠券） 示例值：1300 |
| 货币类型 | currency | string | 是 | 货币类型，仅支持人民币"CNY" 示例值：CNY |
3、通知示例
{
"ToUserName": "gh_xxxxx",
"FromUserName": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o",
"CreateTime": "1698643478",
"MsgType": "event",
"Event": "retail_pay_notify",
"appid": "wx8888888888888888",
"mchid": "1230000109",
"out_trade_no": "1217752501201407033233368018",
"order_id": "o202307291423123564754773",
"pay_status": "ORDER_PAY_SUCC",
"pay_time": "2023-07-20 17:04:28",
"attach": "",
"payer_openid": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o",
"amount": {
"order_amount": 1,
"payer_amount": 1,
"currency": "CNY",
},
"wxpay_transaction_id": "2123191423123564754773",
"env": 0
}
应答参数
直接回复success（推荐方式）
直接回复空串（指字节长度为0的空字符串，而不是结构体中content字段的内容为空）
# 4、查询订单
接口说明
请求地址：https://api.weixin.qq.com/retail/B2b/getorder?access_token=ACCESS_TOKEN&pay_sig=xxxxx
请求方式：POST
请求参数
{
"mchid": "1230000109",
"out_trade_no": "1217752501201407033233368018"
}
或
{
"mchid": "1230000109",
"order_id": "o202307291423123564754773"
}
返回参数
| 参数名 | 变量 | 类型[长度限制] | 必填 | 描述 |
|---|---|---|---|---|
| 小程序ID | appid | string[1,32] | 是 | 商户申请的小程序对应的appid 示例值：wx8888888888888888 |
| 微信商户号 | mchid | string[1,32] | 是 | 由微信支付生成并下发的商户号。 示例值：1230000109 |
| 商户订单号 | out_trade_no | string[6,32] | 是 | 商户系统内部订单号，只能是数字、大小写字母_-*且在同一个商户号下唯一 示例值：1217752501201407033233368018 |
| B2b支付订单号 | order_id | string[1,32] | 是 | B2b支付生成的订单号 示例值：o202307291423123564754773 |
| 订单状态 | pay_status | string[1,32] | 是 | 订单状态，枚举值 ORDER_INIT：订单初始化 ORDER_PRE_PAY：订单预下单成功，待支付 ORDER_PAY_SUCC：订单支付成功 ORDER_CLOSE：订单已关闭 ORDER_REFUND_PROCESSING：订单正在退款中 ORDER_REFUND：订单已有退款 示例值：ORDER_PAY_SUCC |
| 支付完成时间 | pay_time | string[1,32] | 否 | 支付完成时间，标准北京时间，时区为东八区，格式为yyyy-MM-dd HH:mm:ss 示例值：2023-07-20 17:04:28 |
| 附加数据 | attach | string[1,128] | 否 | 附加数据，在查询API和支付通知中原样返回，可作为自定义参数使用，实际情况下只有支付完成状态才会返回该字段。 示例值：自定义数据 |
| 支付者 | payer_openid | string[1,128] | 是 | 用户在直连商户appid下的唯一标识。 示例值：oUpF8uMuAJO_M2pxb1Q9zNjWeS6o |
| 订单金额 | amount | object | 否 | 订单金额信息，仅支持人民币，格式见Amount |
| 微信支付订单号 | wxpay_transaction_id | string[1,32] | 否 | 微信支付生成的订单号 示例值：2123191423123564754773 |
| 订单环境 | env | int32 | 是 | 订单环境 0：正式环境 1：沙箱环境 示例值：0 |
| 错误码 | errcode | int32 | 是 | 接口返回的错误码，0表示成功，非0表示失败 示例值：0 |
| 错误信息 | errmsg | string[1,128] | 是 | 错误信息描述 示例值：OK |
1) Amount
| 参数名 | 变量 | 类型[长度限制] | 必填 | 描述 |
|---|---|---|---|---|
| 订单总金额 | order_amount | int64 | 是 | 订单总需支付金额，也即是真正下单总金额，单位为分 示例值：1300 |
| 用户支付金额 | payer_amount | int64 | 是 | 用户支付金额，单位为分（指使用优惠券的情况下，这里等于总金额-优惠券金额，目前暂不支持优惠券） 示例值：1300 |
| 货币类型 | currency | string | 是 | 货币类型，仅支持人民币"CNY" 示例值：CNY |
通知示例
{
"appid": "wx8888888888888888",
"mchid": "1230000109",
"out_trade_no": "1217752501201407033233368018",
"order_id": "o202307291423123564754773",
"pay_status": "ORDER_PAY_SUCC",
"pay_time": "2023-07-20 17:04:28",
"attach": "",
"payer_openid": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o",
"amount": {
"order_amount": 1,
"payer_amount": 1,
"currency": "CNY",
},
"wxpay_transaction_id": "2123191423123564754773",
"env": 0
"errcode": 0,
"errmsg": OK
}
# 5、退款
当交易发生之后160天内，由于买家或者卖家的原因需要退款时，卖家可以通过退款接口将支付金额退还给买家，微信支付将在收到退款请求并且验证成功之后，将支付款按原路退还至买家账号上。
注：
a、订单如需多次退款，请等待前一次退款完成后再发起调用
b、退款接口只是发起退款请求，不表示退款成功，请2分钟后调用退款查询结果轮询退款状态
接口说明
请求地址：https://api.weixin.qq.com/retail/B2b/refund?access_token=ACCESS_TOKEN&pay_sig=xxxxx
请求方式：POST
请求参数
| 参数名 | 变量 | 类型[长度限制] | 必填 | 描述 |
|---|---|---|---|---|
| 微信商户号 | mchid | string[1,32] | 是 | 由微信支付生成并下发的商户号。 示例值：1230000109 |
| 商户订单号 | out_trade_no | string[6,32] | 否 | 原支付交易对应的商户订单号。商户订单号和B2b支付订单号必填其一 示例值：1217752501201407033233368018 |
| B2b支付订单号 | order_id | string[1,32] | 否 | 原支付交易对应的B2b支付订单号。商户订单号和B2b支付订单号必填其一 示例值：o202307291423123564754773 |
| 商户退款单号 | out_refund_no | string[6, 32] | 是 | 商户系统内部退款单号，商户系统内部唯一，只能是数字、大小写字母_-*，同一退款单号多次请求只退一笔。 示例值：12177525012014070332321235 |
| 退款金额 | refund_amount | int64 | 是 | 退款金额，单位为分，只能为整数，不能超过原订单支付金额。 示例值：888 |
| 退款来源 | refund_from | int32 | 是 | 退款来源，枚举值 1：人工客服退款 2：用户自己退款 3：其他 示例值：1 |
| 退款原因 | refund_reasom | int32 | 否 | 退款原因，枚举值 0：暂无描述 1：产品问题 2：售后问题 3：意愿问题 4：价格问题 5：其他原因 示例值：3 |
请求示例
{
"mchid": "1230000109",
"out_trade_no": "1217752501201407033233368018",
"out_refund_no": "12177525012014070332321235",
"refund_amount": 1,
"refund_from": 2,
"refund_reason": 3
}
返回参数
| 参数名 | 变量 | 类型[长度限制] | 必填 | 描述 |
|---|---|---|---|---|
| B2b支付退款单号 | refund_id | string[1, 32] | 否 | B2b支付退款单号 示例值：r202307281444591411763685 |
| 商户退款单号 | out_refund_no | string[6, 32] | 否 | 商户系统内部退款单号，商户系统内部唯一，只能是数字、大小写字母_-*，同一退款单号多次请求只退一笔。 示例值：12177525012014070332321235 |
| B2b支付订单号 | order_id | string[1,32] | 否 | 原支付交易对应的B2b支付订单号 示例值：o202307291423123564754773 |
| 商户订单号 | out_trade_no | string[6,32] | 否 | 原支付交易对应的商户订单号 示例值：1217752501201407033233368018 |
| 错误码 | errcode | int32 | 是 | 接口返回的错误码，0表示成功，非0表示失败 示例值：0 |
| 错误信息 | errmsg | string[1,128] | 是 | 错误信息描述 示例值：OK |
返回示例
{
"refund_id": "r202307281444591411763685",
"out_refund_no": "12177525012014070332321235",
"order_id": "o202307291423123564754773",
"out_trade_no": "1217752501201407033233368018",
"errcode": 0,
"errmsg": OK
}
# 6、查询退款
接口说明
请求地址：https://api.weixin.qq.com/retail/B2b/getrefund?access_token=ACCESS_TOKEN&pay_sig=xxxxx
请求方式：POST
请求参数
| 参数名 | 变量 | 类型[长度限制] | 必填 | 描述 |
|---|---|---|---|---|
| 微信商户号 | mchid | string[1,32] | 是 | 由微信支付生成并下发的商户号。 示例值：1230000109 |
| 商户退款单号 | out_refund_no | string[6, 32] | 否 | 商户系统内部退款单号，商户系统内部唯一，只能是数字、大小写字母_-*，同一退款单号多次请求只退一笔。商户退款单号和B2b支付退款单号必填其一 示例值：12177525012014070332321235 |
| B2b支付退款单号 | refund_id | string[1, 32] | 否 | B2b支付退款单号。商户退款单号和B2b支付退款单号必填其一 示例值：r202307281444591411763685 |
请求示例
{
"mchid": "1230000109",
"out_refund_no": "12177525012014070332321235"
}
或
{
"mchid": "1230000109",
"refund_id": "r202307281444591411763685"
}
返回参数
| 参数名 | 变量 | 类型[长度限制] | 必填 | 描述 |
|---|---|---|---|---|
| B2b支付退款单号 | refund_id | string[1, 32] | 是 | B2b支付退款单号 示例值：r202307281444591411763685 |
| 商户退款单号 | out_refund_no | string[6, 32] | 是 | 商户系统内部退款单号，商户系统内部唯一，只能是数字、大小写字母_-*，同一退款单号多次请求只退一笔。 示例值：12177525012014070332321235 |
| B2b支付订单号 | order_id | string[1,32] | 是 | 原支付交易对应的B2b支付订单号 示例值：o202307291423123564754773 |
| 商户订单号 | out_trade_no | string[6,32] | 是 | 原支付交易对应的商户订单号 示例值：1217752501201407033233368018 |
| 退款创建时间 | create_time | string[1, 32] | 是 | 退款受理时间，标准北京时间，时区为东八区，格式为yyyy-MM-dd HH:mm:ss。 示例值：2023-07-30 17:04:23 |
| 退款成功时间 | refund_time | string[1, 32] | 否 | 退款成功时间，当退款状态为退款成功时有返回，标准北京时间，时区为东八区，格式为yyyy-MM-dd HH:mm:ss。 示例值：2023-07-30 17:04:28 |
| 退款状态 | refund_status | string[1, 32] | 是 | 退款单状态，枚举值： REFUND_INIT：退款单初始化 REFUND_PROCESSING：退款处理中 REFUND_SUCC：退款成功 REFUND_FAIL：退款失败 示例值：REFUND_SUCC |
| 退款说明 | refund_desc | string[1, 256] | 否 | 退款说明 示例值：账户资金不足，请待充足后重新发起 |
| 金额信息 | amount | object | 是 | 金额详细信息，仅支持人民币，格式见Amount |
| 微信支付退款单号 | wxpay_refund_id | string[1, 32] | 否 | 微信支付退款单号 示例值：1235481444591411763685 |
| 错误码 | errcode | int32 | 是 | 接口返回的错误码，0表示成功，非0表示失败 示例值：0 |
| 错误信息 | errmsg | string[1,128] | 是 | 错误信息描述 示例值：OK |
1) Amount
| 参数名 | 变量 | 类型[长度限制] | 必填 | 描述 |
|---|---|---|---|---|
| 订单总金额 | order_amount | int64 | 是 | 订单总金额，单位为分 示例值：1300 |
| 退款金额 | refund_amount | int64 | 是 | 退款金额，单位为分，可以做部分退款 示例值：100 |
| 货币类型 | currency | string | 是 | 货币类型，仅支持人民币"CNY" 示例值：CNY |
返回示例
{
"refund_id": "r202307281444591411763685",
"out_refund_no": "12177525012014070332321235",
"order_id": "o202307291423123564754773",
"out_trade_no": "1217752501201407033233368018",
"create_time": "2023-07-30 17:04:23",
"refund_time": "2023-07-30 17:04:28",
"refund_status": "REFUND_SUCC",
"amount": {
"order_amount": 1300,
"refund_amount": 100,
"currency": "CNY"
},
"wxpay_refund_id": "1235481444591411763685",
"errcode": 0,
"errmsg": OK
}
# 7、错误码
| 错误码 | 错误描述 | 解决方案 |
|---|---|---|
| 9403200 | 参数为空或不合法 | 按照文档要求传参，根据返回的具体错误描述检查参数 |
| 9403201 | 数据不存在 | 订单或者退款单等要查询的数据不存在，请检查入参 |
| 9403202 | 商户单号重复 | 商户订单号或退款单号重复，请更换单号 |
| 9403203 | 建档未完成，还不能发起支付或退款 | 请完成建档签约流程 |
| 9403205 | 订单无法退款（订单状态不对或超过一年） | 请检查订单状态或订单时间 |
| 9403206 | 退款状态未知，请商户2分钟后主动查询退款状态 | 请2分钟后调用查询退款接口确认退款状态 |
| 9403208 | 该订单正在退款中，请等待退款完成再发起新的退款 | 请等待退款完成再发起新的退款 |
# 3.4 查看账单
# 1、接口下载交易账单与资金账单
接口说明
请求地址： https://api.weixin.qq.com/retail/B2b/downloadbill?access_token=ACCESSTOKEN&pay_sig=xxxxx
请求方式：POST
请求参数
| 字段名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| mchid | string | 是 | 商户号 |
| bill_date | string | 是 | 账单日期，格式:yyyymmdd,比如20231102 |
返回结果
| 字段名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| errcode | int | 是 | 错误码 |
| errmsg | string | 否 | 错误信息 |
| success_bill_url | string | 否 | 支付成功订单下载链接，包括支付成功时间在当天的订单 |
| refund_bill_url | string | 否 | 退款单下载链接，发起退款成功在当天的退款单 |
| all_bill_url | string | 否 | 包括支付成功和退款单的下载链接 |
| fund_bill_url | string | 否 | 资金账单下载链接 |
| ended_day_avail_amt | int | 否 | 日终账户可提现金额 |
| ended_day_frozen_amt | int | 否 | 日终账户待结算金额 |
| ended_day_total_amt | int | 否 | 日终账户总金额，等于日终账户可提现金额+日终账户待结算金额 |
说明
下载链接是https的接口，获取后30天有效
下载后的交易账单文件内容说明：
a. 文件中的内容是以csv文件格式返回，第一行为表头
b. 从第二行起，为数据记录，各参数值以逗号分隔，参数值前增加`符号，为标准键盘1左边键的字符
c. 表头字段顺序与说明：
| 字段名 | 说明 | 示例 |
|---|---|---|
| 交易时间 | 指该笔交易的支付成功时间或发起退款成功时间（注：不是退款成功时间），格式为yyyy-MM-DD HH:MM:SS | 2023-10-23 09:00:00 |
| 公众账号ID | 发起该笔交易时使用的小程序appid | wxab8acb865bb11234 |
| 交易商户号 | 进行交易收款的微信支付子商户号，8~10位数字 | 1234567890 |
| 微信订单号 | 微信小程序平台为该笔订单分配的订单号 | |
| 商户订单号 | 商户传入的该笔订单商户订单号，对应下单接口里的out_trade_no字段 | |
| 用户标识 | 微信为支付用户在公众账号ID(appid)下分配的唯一标识(openid) | |
| 交易状态 | 识该笔明细数据的类型： SUCCESS，支付成功，说明该行数据为一笔支付成功的订单 REFUND，转入退款，说明该行数据为一笔发起退款成功的退款单 | SUCCESS |
| 微信退款单号 | 微信小程序平台为该笔退款分配的退款单号，如果该行数据为订单（交易状态SUCCESS）则展示0 | |
| 商户退款单号 | 商户发起退款时填入的商户退款单号，如果该行数据为订单（交易状态SUCCESS）则展示0 | |
| 退款金额 | 该笔退款单参与计费的应结算金额（申请退款金额-免充值券退款金额），如果该行数据为订单则展示为0.00，非负数、单位元，保留到小数点后2位 | 6.66 |
| 退款状态 | 生成账单文件时该笔退款的状态、出账后不会更新，如果该行数据为订单（交易状态SUCCESS），则留空 SUCCESS：退款成功 PROCESSING：退款处理中 | |
| 商品名称 | 商户传入的该笔订单（或该笔退款对应的订单）的商品名称，对应下单接口里的body字段,目前都为空 | |
| 商户数据包 | 商户传入的该笔订单（或该笔退款对应的订单）的商户数据包，对应下单接口里的attach字段，不传时留空 | |
| 技术服务费 | 该笔订单/退款对应的技术服务费费金额，订单对应正数、退款对应负数，单位元，保留小数点后2位 | 0.01 |
| 技术服务费费率 | 该笔交易收取技术服务费所使用的费率，百分数 | 0.22% |
| 订单金额 | 该笔订单的支付金额，如果该行数据为退款或撤销则填0.00，单位元，保留到小数点后2位 | 2.33 |
| 申请退款金额 | 商户发起退款的金额，包括退给用户的金额、充值券退款金额、免充值券退款金额，如果该行数据订单则填0.00，单位元，保留到小数点后2位 | 2.22 |
| 结算状态 | 生成账单文件时该笔订单的结算状态、出账后不会更新。该笔订单的结算状态： SUCCESS:已结算 NO_SETTLE:未结算 SETTLING:结算中 如果该行数据为退款则为空 | |
| 结算时间 | 结算的时间，在结算状态为"已结算"的时候展示，格式为yyyy-MM-DD HH:MM:SS | 2023-10-23 02:00:00 |
- 下载后的资金账单文件内容说明：
a. 资金账单是针对账户整体（包括可提现部分与待结算部分之和）的资金流入流出变动情况
b. 文件中的内容是以csv文件格式返回，第一行为表头
c. 从第二行起，为数据记录，各参数值以逗号分隔，参数值前增加`符号，为标准键盘1左边键的字符
d. 表头字段顺序与说明：
| 字段名 | 说明 | 示例 |
|---|---|---|
| 记账时间 | 格式为yyyy-MM-DD HH:MM:SS | 2023-10-23 09:00:00 |
| B2b支付业务单号 | 展示该笔资金变动来自的业务。 交易业务：展示支付单号 退款业务：展示退款单号 提现业务：展示提现单号 | |
| 资金流水单号 | 该笔资金变动的系统单号 | |
| 业务名称 | ||
| 业务类型 | ||
| 收支类型 | ||
| 收支金额(元) | 该笔资金变动的金额 | |
| 账户结余(元) | 展示该笔资金变动后，剩余的账户总金额 |
其中，业务名称、业务类型、收支类型有这几种情况：
| 业务名称 | 业务类型 | 收支类型 |
|---|---|---|
| 交易 | 交易 | 收入 |
| 退款 | 退款 | 支出 |
| 交易 | 交易结算扣除手续费 | 支出 |
| 退款 | 已结算退款返还手续费 | 收入 |
| 提现 | 提现 | 支出 |
# 2、后台页面下载交易账单
平台后台页面，提供交易查询、退款查询、以及下载账单能力。
# 3、账单说明
1）技术服务费说明
每笔交易收取的技术服务费=订单金额x技术服务费费率，保留到单位分，最后一位小数按四舍五入。
2）退款返还技术服务费说明
对于退款，平台将根据退款金额返还相关技术服务费。
退款的返还技术服务费规则：
如果为全额退款，则全部返还原来收取的技术服务费；
如果为部分退款，按0.22%计算后保留到单位分，最后一位小数按向下取整（如计算出来返还0.238，实际只返还0.23）
如果经过多笔部分退款后，最后一笔变成全额退款，则最终返还技术服务费的总金额=原来收取的技术服务费
# 3.5 提现
发起提现申请后，需要 T+1 日完成处理并到账。
# 1、手动提现：
对于已结算部分的资金，可在"资金管理"页面中申请提现。
# 2、自动提现：
# 页面端方式：
可前往"基本配置--自动提现"页面，开启自动提现功能。开启后，平台将每天定时发起提现申请。
# 接口端方式：
接口说明
请求地址：https://api.weixin.qq.com/retail/B2b/setautowithdraw?access_token=ACCESS_TOKEN&pay_sig=xxxxx
请求方式：POST
请求参数
| 参数名 | 变量 | 类型[长度限制] | 必填 | 描述 |
|---|---|---|---|---|
| 微信商户号 | mchid | string[1,32] | 是 | 由微信支付生成并下发的商户号。 示例值：1230000109 |
| 自动提现状态 | status | int32 | 否 | 是否开启自动提现，枚举值 1：开启自动提现功能 2：关闭自动提现功能 示例值：1 |
| 自动提现类型 | type | int32 | 否 | 自动提现类型，枚举值 1：提现时账户余额 2：日终账户余额 示例值：2 |
| 留存额 | retain_amt | int64 | 否 | 账户留存金额，单位为分。设置留存额以防提现后账户余额不足，影响退款业务，请根据业务实际情况进行设置。 示例值：500000 |
请求示例
{
"mchid": "1230000109",
"status": 1,
"type": 2,
"retain_amt": 500000
}
返回参数
| 参数名 | 变量 | 类型[长度限制] | 必填 | 描述 |
|---|---|---|---|---|
| 错误码 | errcode | int32 | 是 | 接口返回的错误码，0表示成功，非0表示失败 示例值：0 |
| 错误信息 | errmsg | string[1,128] | 是 | 错误信息描述 示例值：OK |
返回示例
{
"errcode": 0,
"errmsg": OK
}
# 支持两种方案计算自动提现金额：
| 提现金额规则 | 设置留存额规则 | 方案特点 |
|---|---|---|
| 【提现时账户余额】发起提现时的可提现账户余额减留存额 | 设置留存额以防提现后账户余额不足，影响退款业务，请根据业务实际情况进行设置。 当系统自动发起提现时，会根据当时的可提现金额账户余额，减去留存额，作为最终的提现金额。 如果当时的可提现金额账户余额≤留存额，则不发起提现。 | 资金时效性高，当日白天完成的交易结算资金，均可发起提现。 |
| 【日终账户余额】前一日的日终可提现账户余额 | 设置留存额以防提现后账户余额不足，影响退款业务，请根据业务实际情况进行设置。 当系统自动发起提现时，会判断当时的可提现金额账户余额，是否大于"前一日的日终可提现账户余额+留存额"，≥时发起提现，<时不发起。 | 适用于习惯按照日终余额与银行到账金额进行对账的商家。 缺点是资金时效性较低，按照前一日的日终余额进行提现。 |