微信支付-跨境开发者中心

1. 接口说明

适用对象:机构模式

请求URL: https://apihk.mch.weixin.qq.com/v3/global/merchants/{sub_mchid}

请求方式: PATCH

Path指该参数为路径参数

Query指该参数为URL参数

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

2. 请求参数

参数名

变量

类型[长度限制]

必填

描述

机构appid

sp_appid

string[1,32]

是

Body机构在微信公众平台申请服务号对应的APPID
注意：仅适用于机构模式
示例值：wx8888888888888888

机构商户号

sp_mchid

string[1,32]

是

Body微信支付分配的机构商户号
注意：仅适用于机构模式
示例值：3200000001

子商户全称

name

string[1,128]

是

Body子商户公司注册的名称
示例值：Merchant name

子商户号

sub_mchid

string[1,32]

是

path Sub-merchant ID
示例值: 20000100

子商户简称

shortname

string[1,64]

是

Body子商户简称，用于微信订单详情和支付成功页展示
示例值：Merchant shortname

公司电话

office_phone

string[1,32]

是

Body公司电话
示例值：075586010000

联系人信息

contact

object

是

Body联系人信息，详细说明见

参数名	变量	类型[长度限制]	必填	描述
联系人名称	name	string[1,64]	是	联系人名称，该字段需进行加密处理，加密方法详见下面说明示例值：李先生
联系人电话	phone	string[1,32]	是	联系人电话，该字段需进行加密处理，加密方法详见下面说明示例值：075586010000
联系人邮箱	email	string[1,256]	是	联系人邮箱，该字段需进行加密处理，加密方法详见下面说明示例值：test@test.com

类目

business_category

int

是

Body参考附录，详见商业类目列表
示例值：644

渠道号

channel_id

string[1,20]

否

Body机构在微信商户管理后台创建的渠道号，如有渠道号请填写
示例值：3200000001

注册国家或区域

merchant_country_code

string[1,3]

是

Body子商户公司注册的国家或区域
示例值：344

商户类型

merchant_type

string[1,10]

是

Body 取值ENTERPRISE或INDIVIDUAL
若商户为自然人或独资经营者，请选择INDIVIDUAL。
示例值：ENTERPRISE

公司注册文件编号

registration_certificate_number

string[1,50]

是

Body 公司注册文件编号。
若商户为自然人，请提供董事或负责人的ID号。
若商户为独资经营者，请提供独资经营的业务资质证书编号。
示例值：5555-8888

公司注册文件过期时间

registration_certificate_date

string[1,10]

是

Body 公司注册文件过期时间。
取值为过期的日期或取值为“PERMANENT”，“N/A”, 若取值为日期，格式为YYYY-MM-DD，比如2020-10-16。
若商户为自然人，请提供董事或负责人的ID号过期日期。
若商户为独资经营者，请提供独资经营的业务资质证书编号过期日期。
示例值：2020-10-16

公司注册文件照片

registration_certificate_copy

string[1,128]

否

Body公司注册文件的照片，取值为《上传图片API（For HK）》返回的media ID.
示例值：w7yQFawBtja5uEdm_aoXokv2SDoEmHIPs

子商户银行结算账户信息

settlement_bank_number

string[1,128]

否

Body子商户的结算银行账户信息
示例值：555588889999

业务信息

business

object

是

Body业务信息，具体请参考business对象列表

参数名	变量	类型[长度限制]	必填	描述
业务类型	business_type	string[1,7]	是	业务类型为ONLINE，OFFLINE或BOTH 示例值：BOTH
APP下载链接	app_download	string[1,128]	是/否	商户APP的下载地址，当业务类型取值为ONLINE或BOTH时，app_download, bus_website，office_account, mini_program四项中至少选择一项传入示例值：https://download.qq.com
业务网站	website	string[1,128]	是/否	当业务类型取值为ONLINE或BOTH时，app_download, bus_website，office_account, mini_program四项中至少选择一项传入示例值：https://www.qq.com
公众号	office_account	string[1,128]	是/否	当业务类型取值为ONLINE或BOTH时，app_download, bus_website，office_account, mini_program四项中至少选择一项传入示例值：wx8888888888888888
小程序	mini_program	string[1,128]	是/否	当业务类型取值为ONLINE或BOTH时，app_download, bus_website，office_account, mini_program四项中至少选择一项传入示例值：wx8888888888888888
门店地址	store_address	string[1,128]	是/否	商户门店地址，当业务类型取值为OFFLINE或BOTH时必传示例值：10F World Finance Centre (South Office), 11 Canton Road, Tsim Sha Tsui, Hong Kong
门店照片	store_photos	string[1,1024]	否	商户门店照片，当业务类型取值为OFFLINE或BOTH时建议填写（非必填）。至少上传三张门店照片，取值为上传图片API返回的media ID。多个图片，使用Json数组格式提交。示例值：["1beSM1UtWFrTTtCNYOrlllzaoIwc-RjARO-AP_QprCc", "1beSM1UtWFrTTtCNYOrlliXeq8spgRNG46iLYGMaeqc", "1beSM1UtWFrTTtCNYOrllooH4tOjn3F-NKYa_K6dAV8"]
MCC码	mcc	string[1,4]	是/否	Mcc码，详见商户行业编码示例值：4214

董事信息

director

object

是/否

Body董事信息，当商户类型为ENTERPRISE必传，具体请参考director对象列表

参数名	变量	类型[长度限制]	必填	描述
董事姓名	name	string[1,128]	否	董事姓名，当商户类型为ENTERPRISE时选择填入示例值：Bob
董事证件号	number	string[1,128]	否	董事证件号码，当商户类型为ENTERPRISE时选择填入示例值：5555-8888

负责人信息

principal

object

是/否

Body负责人信息，当商户类型为INDIVIDUAL必传，具体请参考principal对象列表

参数名	变量	类型[长度限制]	必填	描述
负责人姓名	name	string[1,128]	否	负责人姓名，当商户类型为INDIVIDUAL时选择填入示例值：Bob
负责人证件号	number	string[1,128]	否	负责人证件号，当商户类型为INDIVIDUAL时选择填入示例值：5555-8888

是否申请H5支付权限

apply_h5_payment

boolean

否

是否为子商户申请H5支付权限。需要申请H5支付权限时此字段为true。
如已有H5支付权限但需要修改H5支付域名，需要填写为true。
示例值：true

H5支付申请资料资料

h5_payment_apply_info

object

否

BodyH5申请资料，需要申请H5支付权限时填写。

参数名	变量	类型[长度限制]	必填	描述
H5经营网址	website_url	string[1,128]	否	apply_h5_payment为true时必填。包含该子商户的主营业务、销售商品/服务及价格、用户可在线下单购买的网址。示例值：https://qq.com
H5支付域名	domains	array	否	apply_h5_payment为true时必填。拉起H5支付的域名，不超过5个；以json数组格式提交。注意：提交的修改的域名列表会覆盖已有支付域名列表。示例值：["www.qq.com","www.weixin.com"]

敏感字段加密说明：对于包含了敏感信息的参数，如联系方式等，我们增加了“字段加密”的安全机制，保护敏感信息只能被数据的接收方看到。

加密步骤：

1、获取微信支付平台证书和对应的平台证书序列号，获取微信支付平台证书。本接口请求http头的“Wechatpay-Serial”需要传平台证书序列号。

2、使用微信支付平台证书的公钥，对于需要加密的参数值进行RSA加密。Java语言的加密方法的填充方案使用 RSA/ECB/PKCS1Padding ;PHP填充方式为OPENSSL_PKCS1_PADDING。

3、加密后的密文，使用base64编码后，作为请求中相应参数的值。

请求示例

JSOM


{
  "sp_appid": "wx82ec4jy334ner1",
  "sp_mchid": "2422128905",
  "name": "Merchant name",
  "shortname": "Merchant shortname",
  "office_phone": "+86075586010000",
  "contact": {
    "name": "yuhZiIh1C8x2UQ9FZY9ojV65HmpttQUSeOi3MdWy52ZoQUSpBUb52dJ+puGkzeGzjuXxJHbD0EGMDOfikdsAr7sqXhqfJexJKN7TSrwewbJqOEJ7fFjB3fqGVu6b/gfq6HduulBgaAlwZ5RcxpEVrAVM54mY3Z9HiX21fcqs65bti/QjEVCg0e1LlypKR3eqdW/XZi3q0gQ3hI0J9crA9OekIGc3M6OZ34aue5VdOd0PTCT99rIcI6N1VuapH2a7hY3fpgGAGxnYgNhUGsTgNoKso0pVCLEl0OlwvYCqmht3foyXtU/4WwwkpK8oFW1yQP3X7D1jXInEakWDFRAcUw==",
    "phone": "XuafjSrgtiqsSzq4QdPEfrfspphyNnVSp9EKg9gM2/szy6ai+q5geSVE5VRRoQlVfiPYK/cFyTk009Cb8GDQilhL0X0HoxcBpcuRIaaW1+LOfMz0POAonG22yER/0486MhQrfNGaCb8QBTfeiIjZT2RPIpvTNyz6cESDV+Y1cD2JKOfK73MU3XKmgQz4mulb9sKdbNtGJV4wc03cR0Md/lnz9QnW5RulHu3bEwVRwtTSGJuMoZntkYhkn4KMRh/z93ri7wKd+DkIfIDMDTzvA2MUn4LW/PJtiKaNP5sOdpmpsw63kOsx5J32mTU7+0qz654MGayTFMW+fSgHBBNYVw==",
    "email": "m+6RSfdEWSAZfrSfrP+FAPzh+jrFPQDPVCaslWwN3EdmsTliLvrUdcYnYuiILHpkZv1E6NNo592KOeznsDrKKWio00qfrurMhTAlneucHfU64yTvIsA6YqeBf8Uqfdad2BG0mYqbIn7AunnE2xqCoqS4W/lJPPROP7VU2/rFzkJx0KMInCo9FErktmN9nNQfhK5dpVis+YNv5SBQ7xSaVAUkTio4xNap1CWpVUIn8CjMgaSa7XJAOwNrNE6+ohU3pA/wlPALNIzYnNu/tktVYnuCm7yA+6wmCrzlWoIC68EgrzzaHZ6Yu59kvibfsMWerSkXRuYT9QNHN8Oe9MdcAQ=="
  },
  "business_category": 644,
  "merchant_country_code": "344",
  "merchant_type": "INDIVIDUAL",
  "registration_certificate_number": "5555-8888",
  "registration_certificate_date": "2025-08-27",
  "registration_certificate_copy": "w7yQFawBtja5uEdm_aoXokv2SDoEmHIPs",
  "business": {
    "business_type": "BOTH",
    "website": "http://www.qq.com",
    "store_address": "shenzhen nanshan tencent",
    "mcc": "5045"
  },
  "apply_h5_payment": true,
  "h5_payment_apply_info": {
    "website_url": "http://www.qq.com",
    "domains": ["www.qq.com", "www.wechat.com"]
  }
}


{
    "appid": "wx2421b1c4370ec43b",
    "m",
      "device_id" : "013467007045764",
      "operator_id": "P001",
      "store_info" : {
        "id": "SZTX001"
      }
    }
}


									{
										"stock_id": ".NET",
										"limit": 10,
									}


									{
										"stock_id": "Python",
										"stock_creator_mchid": "123456",
										"limit": 10,
									}

3. 返回参数

正常返回

参数名	变量	类型[长度限制]	必填	描述
子商户号	sub_mchid	string[1,32]	是	微信支付分配的子商户号注意：仅适用于机构模式示例值：1900000109
H5支付权限状态	h5_authorization_state	string[1, 32]	否	apply_h5_payment为YES时返回，描述子商户的H5支付权限状态： APPROVED：已有H5权限 UNAUTHORIZED：未获得H5权限，也未申请过H5权限 UNDER_REVIEW：H5权限申请当前在审核中 REJECTED：H5权限申请被驳回 UNDER_PUNISHMENT：曾经申请并获得H5权限，但当前权限被处罚，请联系BD处理； APPLICATION_FAILED：H5权限申请单创建失败示例值：APPROVED

异常返回

参数名

变量

类型[长度限制]

必填

描述

返回状态码

code

string[1, 32]

是

错误码，枚举值见错误码列表
示例值：INVALID_REQUEST

返回信息

message

string[1, 256]

是

返回信息，如非空，为错误原因
示例值：参数格式校验错误

详细的错误描述

detail

object

否

当code为PARAM_ERROR时返回，详细说明见下

参数名	变量	类型[长度限制]	必填	描述
指示错误参数的位置	field	string[1, 256]	是	当错误参数位于请求body的JSON时，填写指向参数的JSON Pointer 当错误参数位于请求的url或者querystring时，填写参数的变量名示例值：#/properties/payer
错误参数的值	value	string[1, 256]	是	错误参数的值示例值：1346177081915535577
具体错误原因	issue	string[1, 256]	是	具体错误原因示例值：与ALLOF schema不符
错误参数的位置	location	string[1, 256]	否	body：错误参数位于请求body的JSON中 url：错误参数位于请求url中 query：错误参数位于请求的querystring中示例值：body

返回示例

正常示例异常示例增加申请H5支付权限选项卡

{
    "sub_mchid": "20000100"
}

{
	"code": "INVALID_REQUEST",
	"message": "Parameter format verification error",
	"detail": {
		"field": "#/properties/payer",
		"value": "1346177081915535577",
		"issue": "与ALLOF schema不符",
		"location": "body"
	}
}

{
  "h5_authorization_state": "APPROVED",
  "sub_mchid": "20000100"
}

4. 错误码

错误码	描述	解决方案
PARAM_ERROR	请求参数未按指引进行填写	具体参数格式可以查看文档
SYSTEM_ERROR	后台系统返回错误	系统异常，请使用原参数重新发起
INVALID_REQUEST	商户系统异常导致，商户权限异常、重复请求支付、证书错误、频率限制、商户号不存在、appid和mchid不存在绑定关系、渠道号不对等	请根据接口返回的详细错误描述信息检查您的程序，具体可以查询detail 字段返回的详细信息
INVALID_REQUEST	没有api创建子商户的权限	请登录商户管理后台人工录入子商户信息
INVALID_REQUEST	商户唯一标识已经存在，请更换	针对不同的子商户，请定义唯一的标识
INVALID_REQUEST	子商户未通过审核，无法修改。	请耐心等待，在审核通过后再次提交。
INVALID_REQUEST	商户被处罚，不允许申请开通H5支付权限。	商户支付权限被处罚，请先联系运营人员解除。
INVALID_REQUEST	提交的H5经营网址或支付域名存在风险，请联系对接BD处理。	经营网址或者H5支付域名命中黑名单，请联系运营人员申请豁免。

WeChat Pay

Feedback

Feedback

Submitted successfully

Feedback

Network exception, please try again later

支付产品

资金类产品

其他产品

修改子商户API

1. 接口说明

2. 请求参数

请求示例

3. 返回参数

正常返回

异常返回

返回示例

4. 错误码