# 一、简介与准入开通

# 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支付能力

示例:
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",
        "retailName": "测试门店名称 A"
        "storeType": "超市",
        "storeAddress": "广东省广州市海珠区创意大道",
        "businessName": "测试企业名称 B",
        "businessId": "223345jjj123445C",
        "managerName": "路人甲",
        "openid": "ooo999=ssssdxdf",
        "managerAuditStatus": 4
    }
}

# 1.5 插件返回的授权信息

返回结构体字段:

参数意义 返回参数 备注
调用状态 status 若未授权则为 false
返回数据 data
错误信息 errorMsg

返回数据字段:

参数意义 参数名称 类型
该小程序是否允许使用此插件 isEnableUsePlugin boolean
该小程序是否已被授权 isGrantRetailInfo boolean
门店登记手机号 phone string
门店名称 retailName string
门店类型 storeType string
门店地址 storeAddress string
企业名称 businessName string
营业执照注册号 businessId string
经营者姓名 managerName string
用于发送消息的id openid string

# 1.6 预录入门店信息api

接口功能:通过本API可提前预录入门店信息。
场景说明:对于已提前预录入门店信息的用户,在登录小程序进行门店认证授权流程时,会默认拉起展示预录入的门店信息,用户一键确认即可完成认证授权,减少用户操作成本,提示认证授权成功率。

B2b 预录入信息

所有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后台页面投放端,可创建面向指定用户群体的群发任务

B2b 模板消息交互说明

# 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次/月)
  13. 订单受理结果通知(不限制下发次数)
  14. 订单退款进度通知(不限制下发次数)
  15. 退货申请受理通知(不限制下发次数)
  16. 订单变动通知(不限制下发次数)
  17. 订单签收通知(不限制下发次数)
  18. 验证码通知(不限制下发次数)
  19. 满意度评价提醒(不限制下发次数)
  20. 月度账单提醒(不限制下发次数)
  21. 协议签约审核结果通知(不限制下发次数)
  22. 电子券已核销通知(不限制下发次数)
  23. 解绑通知(不限制下发次数)

新增模板需求可填写链接B2b门店助手模板新增需求

# 请求参数

参数 说明 必填 备注
type 消息类型 枚举值参考B2b门店助手模板消息汇总列表
content 消息内容的json字符串 消息内容,为json格式的字符串,不同类型对应的字符串示例见模板列表
to_user_list 门店负责人openid列表 门店负责人openid列表,最多一次发送200个openid

注:对于keyword.DATA等”模板消息参数值内容限制说明“参见该链接:模板消息--微信开放文档

# 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] 商品描述,最多 127 字节
示例值:Image形象店-深圳腾大-QQ公仔
订单金额 amount object 订单金额信息,仅支持人民币,格式见Amount
附加数据 attach string[1,128] 附加数据,在查询API和支付通知中原样返回,可作为自定义参数使用,实际情况下只有支付完成状态才会返回该字段。
示例值:自定义数据
商品信息 product_info Object 订单详细商品信息,格式见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
}

应答参数

  1. 直接回复success(推荐方式)

  2. 直接回复空串(指字节长度为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表示成功;9403202表示该退款单号已受理,请查单确认是否为当前发起的退款请求;其他非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

注:pay_sig的计算用现网AppKey

请求参数

参数名 变量 类型[长度限制] 必填 描述
微信商户号 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 订单无法退款(订单状态不对或超过160天) 请检查订单状态或订单时间
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 日终账户总金额,等于日终账户可提现金额+日终账户待结算金额
profit_sharing_bill_url string 分账成功订单下载链接,包括分账成功时间在当天的订单
profit_refund_bill_url string 分账回退单下载链接,发起分账回退成功在当天的退款单

说明

  1. 下载链接是https的接口,获取后30天有效

  2. 下载后的交易账单文件内容说明:

    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
  1. 下载后的资金账单文件内容说明:

​ a. 资金账单是针对账户整体(包括可提现部分与待结算部分之和)的资金流入流出变动情况

​ b. 文件中的内容是以csv文件格式返回,第一行为表头

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

​ d. 表头字段顺序与说明:

字段名 说明 示例
记账时间 格式为yyyy-MM-DD HH:MM:SS 2023-10-23 09:00:00
B2b支付业务单号 展示该笔资金变动来自的业务。
交易业务:展示支付单号
退款业务:展示退款单号
提现业务:展示提现单号
资金流水单号 该笔资金变动的系统单号
业务名称
业务类型
收支类型
收支金额(元) 该笔资金变动的金额
账户结余(元) 展示该笔资金变动后,剩余的账户总金额

其中,业务名称、业务类型、收支类型有这几种情况:

业务名称 业务类型 收支类型
交易 交易 收入
退款 退款 支出
交易 交易结算扣除手续费 支出
退款 已结算退款返还手续费 收入
提现 提现 支出

# 2、后台页面下载交易账单

平台后台页面,提供交易查询、退款查询、以及下载账单能力。

# 3、账单说明

1)技术服务费说明

每笔交易收取的技术服务费=订单金额x技术服务费费率,保留到单位分,最后一位小数按四舍五入。

2)退款返还技术服务费说明

对于退款,平台将根据退款金额返还相关技术服务费。

退款的返还技术服务费规则:

  1. 如果为全额退款,则全部返还原来收取的技术服务费;

  2. 如果为部分退款,按0.22%计算后保留到单位分,最后一位小数按向下取整(如计算出来返还0.238,实际只返还0.23)

  3. 如果经过多笔部分退款后,最后一笔变成全额退款,则最终返还技术服务费的总金额=原来收取的技术服务费

# 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
}
# 支持两种方案计算自动提现金额:
提现金额规则 设置留存额规则 方案特点
【提现时账户余额】发起提现时的可提现账户余额减留存额 设置留存额以防提现后账户余额不足,影响退款业务,请根据业务实际情况进行设置。

当系统自动发起提现时,会根据当时的可提现金额账户余额,减去留存额,作为最终的提现金额。
如果当时的可提现金额账户余额≤留存额,则不发起提现。
资金时效性高,当日白天完成的交易结算资金,均可发起提现。
【日终账户余额】前一日的日终可提现账户余额 设置留存额以防提现后账户余额不足,影响退款业务,请根据业务实际情况进行设置。

当系统自动发起提现时,会判断当时的可提现金额账户余额,是否大于"前一日的日终可提现账户余额+留存额",≥时发起提现,<时不发起。
适用于习惯按照日终余额与银行到账金额进行对账的商家。
缺点是资金时效性较低,按照前一日的日终余额进行提现。

# 3.6 分账

# 1、添加分账方

可以通过 api 方式添加分账方,单个小程序添加的分账接收方上限为 1000。

接口说明

请求地址:https://api.weixin.qq.com/retail/B2b/addprofitsharingaccount?access_token=ACCESS_TOKEN&pay_sig=xxxxx

请求方式:POST

请求参数

参数名 类型 内容 描述 必填
env uint32 环境类型 枚举值:0 - 正式环境;1 - 沙盒环境;
profit_sharing_relation_type string 分账接收方关系类型 枚举值:"RELATION_TYPE_SUPPLIER" - 供应商;"RELATION_TYPE_DISTRIBUTOR" - 分销商;"RELATION_TYPE_SERVICE_PROVIDER" - 服务商;"RELATION_TYPE_PLATFORM" - 平台;"RELATION_TYPE_OTHERS" - 其他;
payee_type string 分账接收方类型 枚举值:"PAYEE_TYPE_EXTERNAL_USER" - 外部用户;"PAYEE_TYPE_EXTERNAL_MERCHANT" - 外部商户;
payee_id string 分账接收方标识 根据payee_type填入openid或商户号:当payee_type="PAYEE_TYPE_EXTERNAL_USER"时填openid;当payee_type="PAYEE_TYPE_EXTERNAL_MERCHANT"时填商户号;
payee_name string 分账接收方名称 当payee_type="PAYEE_TYPE_EXTERNAL_MERCHANT"时,填写商户名称; 否(分账接收方为商户号时必填)

返回结果

参数名 类型 内容 描述
errcode int32 错误码 -
errmsg string 错误信息 -

请求示例

{
    "env": 0,
    "profit_sharing_relation_type": "RELATION_TYPE_SERVICE_PROVIDER",
    "payee_type": "PAYEE_TYPE_EXTERNAL_MERCHANT",
    "payee_id": "1234567890",
    "payee_name": "XXX公司"
}

返回示例

{"errcode":0,"errmsg":"OK"}

错误码说明

errcorde errmsg
210001 添加分账方频繁
210002 添加分账方传入环境参数错误
210003 添加分账方传入账户类型错误
210004 重复添加分账方
210006 单个小程序绑定的分账方超过上限

# 2、删除分账方

可以通过 api 方式删除分账方

接口说明

请求地址:https://api.weixin.qq.com/retail/B2b/delprofitsharingaccount?access_token=ACCESS_TOKEN&pay_sig=xxxxx

请求方式:POST

请求参数

参数名 类型 内容 描述 必填
env uint32 环境类型 枚举值:0 - 正式环境;1 - 沙盒环境;
payee_type string 分账接收方类型 枚举值:"PAYEE_TYPE_EXTERNAL_USER" - 外部用户;"PAYEE_TYPE_EXTERNAL_MERCHANT" - 外部商户;
payee_id string 分账接收方标识 根据payee_type填入openid或商户号:当payee_type="PAYEE_TYPE_EXTERNAL_USER"时填openid;当payee_type="PAYEE_TYPE_EXTERNAL_MERCHANT"时填商户号;

返回结果

参数名 类型 内容 描述
errcode int32 错误码 -
errmsg string 错误信息 -

请求示例

{
    "env": 0,
    "payee_type": "PAYEE_TYPE_EXTERNAL_MERCHANT",
    "payee_id": "1234567890"
}

返回示例

{"errcode":0,"errmsg":"OK"}

错误码说明

errcorde errmsg
210001 删除分账方频繁
210002 删除分账方传入环境参数错误
210003 删除分账方传入账户类型错误
210005 分账接受方已被删除
210007 分账账户不存在

# 3、查询分账方

可以通过 api 方式查询分账方

接口说明

请求地址:https://api.weixin.qq.com/retail/B2b/queryprofitsharingaccount?access_token=ACCESS_TOKEN&pay_sig=xxxxx

请求方式:POST

请求参数

参数名 类型 内容 描述 必填
offset uint32 偏移量 分账方数据起始位置的偏移量,默认值为0
limit uint32 最大数量 返回分账方数据的最大条数,默认值为10

返回结果

参数名 类型 内容 描述
errcode int32 错误码 -
errmsg string 错误信息 -
account_list json list 分账账户信息列表 包含多个RetailProfitSharingAccountInfo对象

RetailProfitSharingAccountInfo对象字段说明:

参数名 类型 内容 描述
sharing_account_type string 分账接收方类型 枚举值:"PAYEE_TYPE_EXTERNAL_USER" - 外部用户;"PAYEE_TYPE_EXTERNAL_MERCHANT" - 外部商户;(与添加分账方 API 中的 payee_type 对应)
sharing_account string 分账接收方标识 类型为外部用户时,表示个人 openid;类型为外部商户时,表示商户号;(与添加分账方 API 中的 payee_id 对应)
add_time uint32 添加时间 -
update_time uint32 更新时间 -
name string 商户名称 类型为外部商户时,返回对应的商户名称

请求示例

{
    "offset": 0,
    "limit": 1000
}

返回示例

{
	"account_list": [{
		"sharing_account_type": "PAYEE_TYPE_EXTERNAL_MERCHANT",
		"sharing_account": "1234567890",
		"add_time": 1724222992,
		"update_time": 1724222992,
		"name": "XXX公司"
	}],
	"errcode": 0,
	"errmsg": "OK"
}

错误码说明

errcorde errmsg
1 查询不到可用分账方

# 4、下单时标识这笔单需要分账

可以通过 api 方式查询分账方

接口说明

请求方式:同3.3 支付与退款调用相同的接口:wx.requestCommonPayment(Object object)

请求参数

在signData具体支付参数字段(Object类型)中,添加need_profit_sharing的字段,数字 0(或者不填)标识不需要分账,数字 1 标识需要分账

返回参数

3.3 支付与退款

请求示例

{
  "signData": "{\"mchid\":\"1654806452\",\"out_trade_no\":\"test1244\",\"description\":\"测试测试\",\"amount\":{\"order_amount\":1,\"currency\":\"CNY\"},\"attach\":\"test_attach\",\"env\":1, \"need_profit_sharing\":1}",
  "mode": "retail_pay_goods",
  "paySig": "xxxxxxxxxx",
  "signature": "xxxxxxxxxx",
}

返回示例

3.3 支付与退款

# 5、请求分账

通过此接口发起分账请求,将结算后的资金分给分账接收方。

单笔订单,单个分账接收方只允许发起一次。单笔订单只允许最多 45 个接收方,总分账比例金额不超过单笔订单总额的29%。

分账资金的冻结期默认是180天。从订单支付成功之日起,180天内需要发起分账,若180天内未发起分账,待分账资金将会自动解冻给分账方。

接口说明

请求URL:https://api.weixin.qq.com/retail/B2b/createprofitsharingorder?access_token=ACCESS_TOKEN&pay_sig=xxxxx

请求方式:POST

请求参数

参数名 类型 内容 描述 必填
mchid string 子商户id 在B2b小程序中进件完成返回的子商户 id
out_trade_no string 支付单 id 在B2b小程序中下单的订单 id
profit_fee uint64 分账费用 单位:分,不超过支付单本身的金额
receiver_type string 分账接收方类型 同添加分账方时填入的内容
receiver_account string 分账接收方账号 同添加分账方时填入的内容

返回参数

参数名 类型 内容 描述
errcode int32 错误码 -
errmsg string 错误信息 -

请求示例

{
	"mchid": "1654806452",
  	"out_trade_no": "400128912435668818922107515929",
    "profit_fee": 100,
    "receiver_type": "PAYEE_TYPE_EXTERNAL_MERCHANT",
  	"receiver_account": "1654806451"
}

返回示例

{
	"errcode": 0,
  	"errmsg": "OK"
}

# 6、查询分账结果

可用于查询某笔支付单的某笔分账单是否已经分账完成。

接口说明

请求URL:https://api.weixin.qq.com/retail/B2b/queryprofitsharingorder?access_token=ACCESS_TOKEN&pay_sig=xxxxx

请求方式:POST

请求参数

参数名 类型 内容 描述 必填
out_trade_no string 支付单 id 在B2b小程序中下单的订单 id
receiver_type string 分账接收方类型 同添加分账方时填入的内容
receiver_account string 分账接收方账号 同添加分账方时填入的内容
mchid string 商户号 商户号

返回参数

参数名 类型 内容 描述
errcode int32 错误码 -
errmsg string 错误信息 -

请求示例

{
  	"out_trade_no": "4001289118922107515929",
    "receiver_type": "PAYEE_TYPE_EXTERNAL_MERCHANT",
  	"receiver_account": "15480651"
}

返回示例

{
	"errcode": 0,
  	"errmsg": "OK",
  	"order_status": 2
}

# 7、查询分账剩余金额

可用于查询某笔支付单还能够分账的总金额。

接口说明

请求URL:https://api.weixin.qq.com/retail/B2b/queryprofitsharingremainamt?access_token=ACCESS_TOKEN&pay_sig=xxxxx

请求方式:POST

请求参数

参数名 类型 内容 描述 必填
mchid string 子商户id 在B2b小程序中进件完成返回的子商户 id
out_trade_no string 订单 id 在B2b小程序中下单的订单 id
env uint32 环境参数 0标识正式(默认值),1 标识沙盒

返回参数

参数名 类型 内容 描述
errcode int32 错误码 -
errmsg string 错误信息 -
remain_amt uint64 冻结金额,单位:分 -

请求示例

{
  	"out_trade_no": "4001289122107515929",
    "mchid": "16548451",
  	"env": 0
}

返回示例

{
	"errcode": 0,
  	"errmsg": "OK",
    "remain_amt": 98
}

# 8、完成分账

某笔支付单在下单时标识需要分账后,该笔支付单的金额会被冻结,直到调用该接口告知完成分账后,金额才会解冻,能够发起提现。

接口说明

请求URL:https://api.weixin.qq.com/retail/B2b/finishprofitsharingorder?access_token=ACCESS_TOKEN&pay_sig=xxxxx

请求方式:POST

请求参数

参数名 类型 内容 描述 必填
mchid string 子商户id 在B2b小程序中进件完成返回的子商户 id
out_trade_no string 订单 id 在B2b小程序中下单的订单 id

返回参数

参数名 类型 内容 描述
errcode int32 错误码 -
errmsg string 错误信息 -

请求示例

{
  	"out_trade_no": "40012891243522107515929",
    "mchid": "1654806451"
}

返回示例

{
	"errcode": 0,
  	"errmsg": "OK"
}

# 9、发起分账的支付单的退款规则说明

订单分账状态 申请退款金额 退款前提 退款出款账户
订单标记为需要分账 申请全额退款 1、需要先调“完成分账”接口,将订单剩余冻结资金从“待结算金额”账户全部解冻至“可提现金额”账户
2、“可提现金额”账户余额≥申请退款金额,支付单扣除手续费将在退款成功后返还
“可提现金额”账户
申请部分退款 当申请退款金额≤订单未分账冻结金额,直接可退 “待结算金额”账户
1、当申请退款金额>订单未分账冻结金额,需要先调“完成分账”接口,将订单剩余冻结资金从“待结算金额”账户全部解冻至“可提现金额”账户
2、“可提现金额”账户余额≥申请退款金额,支付单扣除手续费将在退款成功后返还
“可提现金额”账户
订单已完结分账 申请全额/部分退款 “可提现金额”账户余额≥申请退款金额,支付单扣除手续费将在退款成功后返还 “可提现金额”账户

# 10、请求分账回退

已分账订单,在完成退款后,通过调用此接口,可将已分账的资金从分账接收方的账户回退给分账方。

接口说明

请求URL:https://api.weixin.qq.com/retail/B2b/refundprofitsharing?access_token=ACCESS_TOKEN&pay_sig=xxxxx

请求方式:POST

请求参数

参数名 类型 内容 描述 必填
out_trade_no string 订单 id 在B2b小程序中下单的订单 id
out_refund_no string 退款单 id 在B2b小程序中下单的退款单 id
payee_type string 退款分账方类型 同添加分账方时填入的内容
payee_id string 退款分账方 id 同添加分账方时填入的内容
mchid string 商户号 id 发起这笔订单的商户号
refund_amt int64 退款金额 退款金额,单位为分

返回参数

参数名 类型 内容 描述
errcode int32 错误码 -
errmsg string 错误信息 -

请求示例

{
  	"out_trade_no": "40012891249207515929",
    "out_refund_no": "4001289124357515929",
 	"payee_type": "PAYEE_TYPE_EXTERNAL_MERCHANT",
  	"payee_id": "165406451",
  	"mchid": "166321431"
}

返回示例

{
	"errcode": 0,
  	"errmsg": "OK"
}

# 11、查询分账回退结果

通过此接口查询回退结果。

接口说明

请求URL:https://api.weixin.qq.com/retail/B2b/queryrefundprofitsharingorder?access_token=ACCESS_TOKEN&pay_sig=xxxxx

请求方式:POST

请求参数

参数名 类型 内容 描述 必填
out_trade_no string 订单 id 在B2b小程序中下单后返回的订单 id
out_refund_no string 退款单 id 在B2b小程序中下单后返回的退款单 id
mchid string 商户号 id 发起这笔订单的商户号
payee_type string 退款分账方类型 同添加分账方时填入的内容
payee_id string 退款分账方 id 同添加分账方时填入的内容

返回参数

参数名 类型 内容 描述
errcode int32 错误码 -
errmsg string 错误信息 -
order_status uint32 订单状态 1: 分账退回中
2: 分账退回完成
3: 分账退回失败

请求示例

{
  	"out_trade_no": "40012891243522107515929",
    "out_refund_no": "400128912435605688225929",
 	"payee_type": "PAYEE_TYPE_EXTERNAL_MERCHANT",
  	"payee_id": "165406451",
  	"mchid":"166732131"
}

返回示例

{
	"errcode": 0,
  	"errmsg": "OK",
    "order_status": 2
}

# 12、业务分账账单查询

接口详情请看3.4-查看账单

接口说明

请求URL: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 日终账户总金额,等于日终账户可提现金额+日终账户待结算金额
profit_sharing_bill_url string 分账成功订单下载链接,包括分账成功时间在当天的订单
profit_refund_bill_url string 分账回退单下载链接,发起分账回退成功在当天的退款单

# 13、资金流水账单查询

在原有资金流水下载链接里会包含第三方分账。接口详情请看3.4-查看账单