# 一、简介与准入开通

# 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

请求参数

返回参数

调用示例

请求数据示例

{
    "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"
}

常见错误码

# 二、开发指引

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

# 1.5 插件返回的授权信息

返回结构体字段：

返回数据字段：

# 1.6 预录入门店信息api

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

所有API调用前，需要先获取“接口调用凭证”。

调用方式:

HTTPS 调用

POST https://api.weixin.qq.com/wxa/business/batchcreateretail?access_token=ACCESS_TOKEN

如调用本接口返回错误码4：地址解析失败，可将导入失败的地址数据传入地址解析接口（地址解析接口文档），获取标准化的省、市、区后重新导入。
附：门店助手有效地址组合

请求参数说明：

字段内容举例：

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返回值及含义：

failure_code含义：

# 1.7 门店信息查询api

接口功能：查询已完成门店认证授权用户的门店信息

调用方式:

HTTPS 调用

POST https://api.weixin.qq.com/wxa/business/getretailinfo?access_token=ACCESS_TOKEN

请求参数说明：

响应参数说明：

字段内容举例：

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.8 全量授权门店查询api

调用方式

HTTPS 调用

POST https://api.weixin.qq.com/wxa/business/getretailopenidlist?access_token=ACCESS_TOKEN

请求参数

返回参数

调用示例

请求数据示例

{
    "limit": 100,
    "page_context": ""
}

返回数据示例

{
    "errcode": 0,
    "errmsg": "ok",
    "openid_list": ["openid1", "openid2", "..."],
    "page_context": "page_context1"
}

常见错误码

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

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

# 请求参数

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

# 2.3 错误码说明

# 2.4 消息效果数据api

调用方式

HTTPS 调用

POST https://api.weixin.qq.com/wxa/business/getretailmessagelist?access_token=ACCESS_TOKEN

请求参数

返回参数

调用示例

请求数据示例

{
  "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"
        }
    ]
}

常见错误码

# 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": 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"
}

错误码

# 接口端方式：上传商户图片 API

可以通过api 上传资料获取图片 id，进件时填充图片 id

接口说明

请求URL：https://api.weixin.qq.com/retail/B2b/retailuploadmchfile?access_token=ACCESS_TOKEN

请求方式：POST

请求参数

返回参数

# 2、查询商户号开通状态

# 页面端方式：

登录mp.weixin.qq.com，进入小程序后台页面，在"门店助手-支付管理"栏目，可随时查看最新的申请进度。

# 接口端方式：查询商户号进件状态API

可以通过api方式查询商户号进件订单（包含状态信息等）

接口说明

请求URL：https://api.weixin.qq.com/retail/B2b/retailgetmchorder?access_token=ACCESS_TOKEN

请求方式：POST

请求参数

返回参数

# 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": "123",
  "profit_rate": 20,
}

返回示例

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

错误码

# 3.3 支付与退款

# 1、签名详解

在基础库wx.requestCommonPayment会涉及用户态签名signature和支付签名paySig，在服务器API接口会涉及支付签名pay_sig，和小程序接口的paySig签名方式一致，都遵循本签名详解。

支付签名

签名算法伪代码为 signature = to_hex(hmac_sha256(sessionKey,signData))

用户态签名

签名算法伪代码为：

signature = to_hex(hmac_sha256(sessionKey,signData))

参考的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)

请求参数

1) signData

2）Amount

3）ProductInfo

请求示例

{
  "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 回调函数

object.fail 回调函数

错误码

# 3、支付通知

接口说明

通过消息推送功能发送给业务方服务器，业务方按照消息推送的要求回复，否则会认为通知失败。通知失败后会按照一定的策略重新发起通知，以尽可能通知到商户，但并不保证通知最终能成功。（通知重试频率为10s, 30s, 60s, 5min, 15min, 30min, 60m, 3h, 6h, 12h）

通知参数

1) Amount

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"
}

返回参数

1) Amount

通知示例

{
  "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": "1230000109",
  "out_trade_no": "1217752501201407033233368018",
  "out_refund_no": "12177525012014070332321235",
  "refund_amount": 1,
  "refund_from": 2,
  "refund_reason": 3
}

返回参数

返回示例

{
  "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": "1230000109",
  "out_refund_no": "12177525012014070332321235"
}
或
{
  "mchid": "1230000109",
  "refund_id": "r202307281444591411763685"
}

返回参数

1) Amount

返回示例

{
  "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、错误码

# 3.4 查看账单

# 1、接口下载交易账单与资金账单

接口说明

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

请求方式：POST

请求参数

返回结果

说明

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

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

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

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

   c. 表头字段顺序与说明：

3. 下载后的资金账单文件内容说明：

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

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

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

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

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

# 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": "1230000109",
  "status": 1,
  "type": 2,
  "retain_amt": 500000
}

返回参数

返回示例

{
  "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": 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"}

错误码说明

# 2、删除分账方

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

接口说明

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

请求方式：POST

请求参数

返回结果

请求示例

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

返回示例

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

错误码说明

# 3、查询分账方

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

接口说明

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

请求方式：POST

请求参数

返回结果

RetailProfitSharingAccountInfo对象字段说明：

请求示例

{
    "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"
}

错误码说明

# 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": "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": "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

请求参数

返回参数

请求示例

{
  	"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

请求参数

返回参数

请求示例

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

返回示例

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

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

# 10、请求分账回退

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

接口说明

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

请求方式：POST

请求参数

返回参数

请求示例

{
  	"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": "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

请求参数

返回参数

# 13、资金流水账单查询

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