提交商家名片配置申请

更新时间:2025.11.13

本接口面向服务商(不包括银行、支付机构、电商平台),用于提交商家名片配置申请,支持配置商家服务列表(用户可点击跳转至小程序或网页)和多渠道客服信息(包括自研客服、客服电话等),配置提交后返回名片预览二维码链接供商家验证跳转路径是否符合预期。

注意:接口采用全量覆盖机制,每次提交均视为完整配置。最新提交将完全覆盖历史配置,不支持多轮次增量更新,请确保每次请求包含完整的配置信息。

接口说明

支持商户:【普通服务商】

请求方式:【POST】/v3/brand/card/card-configs

请求域名:【主域名】https://api.mch.weixin.qq.com 使用该域名将访问就近的接入点

     【备域名】https://api2.mch.weixin.qq.com 使用该域名将访问异地的接入点 ,指引点击查看

接口限频:1/秒(商户号维度)

请求参数
折叠全部参数

Header  HTTP头参数

 Authorization  必填 string

请参考签名认证生成认证信息


 Accept  必填 string

请设置为application/json


 Content-Type  必填 string

请设置为application/json


body  包体参数

 business_code  必填   string(128)

【业务申请编号】 1、只能由数字、字母或下划线组成;
2、服务商自定义的商户唯一编号,每个编号对应一个申请单;
3、若申请被驳回,可填写相同的“业务申请编号”,即可覆盖修改原申请信息。


 brand_id  必填   string(20)

【品牌ID】 商家进驻微信支付品牌商家后获得的品牌ID,作为品牌唯一标识符。


 brand_mini_program_info  选填   object

【品牌小程序信息】 用于配置商家名片头部跳转的小程序,建议配置用户在品牌发起交易的小程序。

属性

 appid  必填   string(50)

【公众账号ID】 1、公众账号ID也称 AppID,是(微信开放平台、微信公众平台)为开发者提供的一个唯一标识,用于识别开发者的应用程序(APP、小程序、公众号);开发者需要在微信开放平台微信公众平台中申请ID。
2、请填写配置商家名片头部跳转小程序的 AppID。


 default_jump_path  选填   string(512)

【小程序默认跳转路径】 商家名片头部跳转小程序的默认路径,不填写则默认跳转小程序首页。


 button_text  选填   string(10)

【小程序跳转按钮文案】 商家可自定义小程序跳转按钮的显示文案,如未设置则默认显示"前往小程序"。


 brand_customer_service  必填   object

【品牌客服信息】 1、品牌客服信息配置,用于在商家名片中展示客服信息;
2、根据客服类型不同,需要填写对应的配置信息。

属性

 customer_service_type  必填   string

【客服类型】 客服类型枚举,用于配置商家名片中的客服信息。

可选取值

  • MINI_PROGRAM:  小程序官方客服组件:小程序官方提供的客服组件,需传入小程序 AppID,详细见链接

  • WECOM:  企业微信客服:企业微信官方提供的微信客服组件,详细见概述

  • CUSTOMIZE_WEB:  自建客服(网页):品牌自主或通过第三方搭建的客服系统,在网页内向用户提供咨询服务,传入网页链接即可

  • CUSTOMIZE_MP:  自建客服(小程序):品牌自主或通过第三方搭建的客服系统,在小程序内向用户提供咨询服务,需传入小程序 AppID 及小程序路径

  • SERVICE_PHONE:  客服电话:品牌官方客服电话


 customer_service_phone  选填   string(20)

【客服电话】 1、品牌官方客服电话,需确保电话号码真实有效;
2、当客服类型是"客服电话"时必填。


 customer_service_path  选填   string(1024)

【客服路径】 1、客服页面的具体路径,需确保路径真实存在;
2、当客服类型是"企业微信客服"、"自建客服(网页)"、"自建客服(小程序)"时必填。


 appid  选填   string(50)

【公众账号ID】 1、公众账号ID也称 AppID,是(微信开放平台、微信公众平台)为开发者提供的一个唯一标识,用于识别开发者的应用程序(APP、小程序、公众号);开发者需要在微信开放平台微信公众平台中申请ID。
2、当客服类型是"小程序官方客服组件"、"自建客服(小程序)"时必填;
3、请使用已认证的小程序 AppID。


 service_list  选填   array[object]

【服务列表】 1、用于在商家名片中展示品牌提供的各项服务;
2、条件:如需要配置服务,则至少填写2项,最多15项;如无需配置服务,则保持列表为空;
3、列表排序:列表顺序即为最终展示顺序,系统将按输入顺序对服务进行分类和排序,相同服务分类的项会自动归组,组内顺序保持数组中的原始排列。

属性

 service_classify_name  必填   string(6)

【服务分类名称】 商家名片服务列表中的服务分类名称,多个服务可以归属为一个服务分类,最多可创建三个服务分类。


 service_name  必填   string(8)

【服务名称】 商家名片服务列表中的服务名称,一个服务分类下最多可配置5个服务名称,整个服务列表最多可配置15个服务名称。


 service_jump_type  必填   string

【服务跳转类型】 决定了用户点击服务后的跳转方式。

可选取值

  • JUMP_MINI_PROGRAM:  小程序:小程序页面路径

  • JUMP_WEB_PAGE:  网页:完整的网页URL,必须是HTTPS协议


 service_jump_path  必填   string(1024)

【服务跳转路径】 服务跳转路径,根据服务跳转类型不同,格式要求不同。


 appid  选填   string(50)

【公众账号ID】 1、公众账号ID也称 AppID,是(微信开放平台、微信公众平台)为开发者提供的一个唯一标识,用于识别开发者的应用程序(APP、小程序、公众号);开发者需要在微信开放平台微信公众平台中申请ID。
2、当服务跳转类型是小程序时,需传入对应小程序的 AppID。
3、请使用已认证的小程序 AppID。

请求示例

curl
Java
Go

POST

1curl -X POST \
2  https://api.mch.weixin.qq.com/v3/brand/card/card-configs \
3  -H "Authorization: WECHATPAY2-SHA256-RSA2048 mchid=\"1900000001\",..." \
4  -H "Accept: application/json" \
5  -H "Content-Type: application/json" \
6  -d '{
7    "business_code" : "1900013511_10000",
8    "brand_id" : "1234567",
9    "brand_mini_program_info" : {
10      "appid" : "wx1234567890abcdef",
11      "default_jump_path" : "pages/shop/index",
12      "button_text" : "前往小程序"
13    },
14    "brand_customer_service" : {
15      "customer_service_type" : "MINI_PROGRAM",
16      "customer_service_phone" : "12345678900",
17      "customer_service_path" : "pages/service/index",
18      "appid" : "wx1234567890abcdef"
19    },
20    "service_list" : [
21      {
22        "service_classify_name" : "会员服务",
23        "service_name" : "会员中心",
24        "service_jump_type" : "JUMP_MINI_PROGRAM",
25        "service_jump_path" : "pages/shop/index",
26        "appid" : "wx1234567890abcdef"
27      }
28    ]
29  }'
30

应答参数

200 OK

 business_code  必填   string(128)

【业务申请编号】 1、只能由数字、字母或下划线组成;
2、服务商自定义的商户唯一编号,每个编号对应一个申请单。


 applyment_id  必填   string(25)

【微信支付申请单号】 申请单的唯一标识,由微信支付生成。


 brand_id  必填   string(20)

【品牌ID】 商家进驻微信支付品牌商家后获得的品牌ID,作为品牌唯一标识符。


 card_preview_url  必填   string(512)

【商家名片预览二维码链接】 商家名片配置申请提交成功后,将返回可供商家预览的二维码链接,商家可查看各跳转路径是否正常,符合预期。


 url_expired_time  必填   string(64)

【预览二维码链接过期时间】 1、商家名片配置申请提交成功后,系统将返回预览二维码链接的有效截止时间。商家需在此时间点前完成预览确认,逾期链接将自动失效。
2、格式:遵循rfc3339标准格式:yyyy-MM-DDTHH:mm:ss+TIMEZONEyyyy-MM-DD 表示年月日;T 字符用于分隔日期和时间部分;HH:mm:ss 表示具体的时分秒;TIMEZONE 表示时区(例如,+08:00 对应东八区时间,即北京时间)。
示例:2025-05-20T13:29:35+08:00 表示北京时间2025年5月20日13点29分35秒。

应答示例

200 OK

1{
2  "business_code" : "1900013511_10000",
3  "applyment_id" : "1111111111",
4  "brand_id" : "1234567",
5  "card_preview_url" : "https://pay.weixin.qq.com/xdc/mchcardinfomgrweb/miniapp?link_id=12345",
6  "url_expired_time" : "2025-05-20T13:29:35+08:00"
7}
8

 

错误码

以下是本接口返回的错误码列表。详细错误码规则,请参考微信支付接口规则-错误码和错误提示

状态码

错误码

描述

解决方案

400

PARAM_ERROR

参数错误

请根据错误提示正确传入参数

400

INVALID_REQUEST

HTTP 请求不符合微信支付 APIv3 接口规则

请参阅 接口规则

401

SIGN_ERROR

验证不通过

请参阅 签名常见问题

500

SYSTEM_ERROR

系统异常,请稍后重试

请稍后重试

400

RESOURCE_ALREADY_EXISTS

存在在途商家名片配置申请单

可通过"查询申请状态"接口查看此申请单的申请状态,或更换业务申请编号提交新的申请单

403

NO_AUTH

商户权限异常

请确认是否已经开通相关权限

429

RATELIMIT_EXCEEDED

频率限制

请降低调用频率

 

元宝AI
反馈
目录
置顶