API Dictionary / Merchant Onboard / Query Sub-merchant API

Query Sub-merchant API

Latest update time：2024.03.27 Release notes

It is used by the institution to view whether the sub-merchant has been successfully created. The API is only used for a single sub-merchant check.

Tips：

• The {sub_mchid} in the URL refers to the Sub-merchant ID to be viewed.

1. API Intro

Applicable object： Institutional mode

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

Request method：GET

Pathparameter is a path parameter.

Queryparameter needs to be passed in the request URL.

Bodyparameter needs to be passed in the request JSON.

2. Request Parameters

Name	Variable Name	Type	Required	Description
Institution's Merchant ID	sp_appid	string[1,32]	Yes	Query Merchant ID assigned to institutions by WeChat Pay Note:Only forInstitutional mode Example: wx8888888888888888
Organization APPID	sp_mchid	string[1,32]	Yes	Query APPID corresponding to the Service Account applied for by the institution on the WeChat Official Accounts Platform Note:Only forInstitutional mode Example: 3200000001
Sub-merchant ID	sub_mchid	string[1,32]	Yes	Path Sub-merchant ID Example: 20000100

Request Eample：

URL


https://apihk.mch.weixin.qq.com/v3/global/merchants/20000100?sp_appid=wx8888888888888888&sp_mchid=1900000100


{
  "currency": "CNY",
  "out_trade_no": "P20150806125346",
  "sub_mchid": "1900000109"
}


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


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

3. encryption guide

Note on sensitive field encryption：

For parameters that contain sensitive information, such as contact information, a "field encryption" security mechanism is provided to make sure that the sensitive information can only be seen by the data recipient.

Encryption procedures

1、Perform the RSA encryption for the parameter values with the public key of the WeChat Pay Platform certificate. Use `RSAES-PKCS1-v1_5` as the filling scheme.

2、The encrypted ciphertext that is encoded with base64 is used as the value of the appropriate parameter in the request.

4. Response Parameters

Response for successful request:

Name

Variable Name

Type

Required

Description

Submerchant id

sub_mchid

string[1,32]

Yes

Specifies the sub merchant ID assigned by WeChat
Example: 20000100

Full name of the sub-merchant

name

string[1,128]

Yes

The registration name of the sub-merchant
Example: Merchant name

Short name of the sub-merchant

shortname

string[1,64]

Yes

The short name of the sub-merchant, which is used for the display of WeChat order details and the successful payment page
Example: Merchant shortname

Company contact information

office_phone

string[1,32]

Yes

Contact information of the merchant, which will be displayed to the user after the payment.
Example: 075586010000

Registered Country or Region

merchant_country_code

string[1,3]

Yes

The country where the submerchant was registered ,see to CountryCode
Example: 344

Business category

business_category

int

Yes

Specifies the business category, please refer to the business ID list of WeChat payment. Please see Business Category
Example: 101

Contact information

contact

object

Contact information object details is listed below

Name	Variable Name	Type	Required	Description
Full Name	name	string[1,64]	No	Specifies the contact person’s name. Example: Bob Zhang
Mobile Phone No.	phone	string[1,32]	No	Specifies the mobile phone number of the merchant for any urgent issues. Please prefix the phone number. See the appendix for prefixes. Example: +8613633334444
Email	email	string[1,256]	No	Specifies the contact email of the merchant. Example: test@test.com

pack up

Merchant Type

merchant_type

string[1,10]

ENTERPRISE or INDIVIDUAL
Example: ENTERPRISE

Registration Certificate Number

registration_certificate_number

string[1,50]

Company registration document Number
Example: 5555-8888

Expiration Date of Registration Certificate

registration_certificate_date

string[1,10]

The expiration date of the company registration document.
The value should be expire date or “PERMANENT” , “N/A”, the date format should YYYY-MM-DD
Example: 2020-10-16

Settlement Bank No.

settlement_bank_number

string[1,128]

Settlement bank account number (settlement bank information)
Example: 555588889999

Business information

business

object

Business information, the detail is listed below

Name	Variable Name	Type	Required	Description
Business type	business_type	string[1,7]	No	There are three business types:ONLINE, OFFLINE or BOTH Example: BOTH
Download link of APP	app_download	string[1,128]	No	The download link of merchant’s APP. Example: https://download.qq.com
Business website	website	string[1,128]	No	The business website, app_download Example: https://www.qq.com
Official account	office_account	string[1,128]	No	Merchant’s official account. Example: wx8888888888888888
Mini Program	mini_program	string[1,128]	No	Merchant’s mini program. Example: wx8888888888888888
Store address	store_address	string[1,128]	No	Store address. Example: 10F World Finance Centre (South Office), 11 Canton Road, Tsim Sha Tsui, Hong Kong
MCC	mcc	string[1,4]	No	Mcc code, Please see Merchant category codes Example: 4214

pack up

Director information

director

object

Director information,
The detail is listed below

Name	Variable Name	Type	Required	Description
Director Name	name	string[1,128]	No	Director name. Example: Bob
Director ID Number	number	string[1,128]	No	Director's ID number. Example: 5555-8888

pack up

Principal information

principal

object

Principal information,
The detail is listed below

Name	Variable Name	Type	Required	Description
Principal Name	name	string[1,128]	No	Principal's ID number. Example: Bob
Principal ID Number	number	string[1,128]	No	Principal's ID number. Example: 5555-8888

pack up

H5 payment application details

h5_payment

object

H5 payment application detail

Name	Variable Name	Type	Required	Description
Full Name	name	string[1,64]	No	Specifies the contact person’s name. Example: Bob Zhang
H5 audit reject detail	audit_reject_detail	string[1,1024]	No	Returned when H5 payment authorization state is REJECTED or APPLICATION_FAILED; reason for rejected or unsuccessful request. Example: Merchant certificate is invalid.
H5 payment authorization state	h5_authorization_state	string[1,32]	No	Returned when apply_h5_payment is true; describe the H5 payment authorization state of the sub-merchant: APPROVED: H5 payment authorization already granted; UNAUTHORIZED: H5 payment authorization not granted, no H5 authorization application submitted; UNDER_REVIEW: H5 payment authorization application is currently under review; REJECTED: H5 payment authorization application has been rejected, please check the reason for the rejection in audit_reject_detail; UNDER_PUNISHMENT: H5 payment authorization has been applied and granted, but sub-merchant is currently being penalized; APPLICATION_FAILED: Failed to create the H5 payment authorization application, please check the reason in audit_reject_detail. Example: APPROVED

pack up

Sub-merchant's status info

sub_merchant_state

object

Sub-merchant's status info

Name

Variable Name

Type

Required

Description

Sub-merchant's status

sub_merchant_status

string[1,32]

Sub-merchant's status refers to the status of the sub-merchant in the WeChat Pay system:
OPERATING: Normal; the sub-merchant has normal payment authorization and can initiate transactions.
PENDING: Pending; the sub-merchant's information has not passed regular review and the institution is required to log in to the WeChat Pay merchant platform to check and process it. The sub-merchant has normal payment authorization and can initiate transactions.
DEACTIVATED: The sub-merchant has been deactivated; the institution has suspended the sub-merchant account and the sub-merchant has no payment authorization and cannot initiate any transaction.
CLOSED: The sub-merchant has been closed; WeChat Pay has disabled the sub-merchant's payment authorization and the sub-merchant cannot initiate any transaction.
INCOMPLETE_APPLICATION: Onboarding process is incomplete; the sub-merchant's onboarding application is incomplete and has no payment authorization and cannot initiate any transaction. Please check the onboarding application status in the application_status field.
Example: OPERATING

Sub-merchant's onboarding status

application_status

string[1,32]

Returned when the sub-merchant's onboarding status is "INCOMPLETE_APPLICATION"; Sub- merchant onboarding application status:
UNDER_REVIEW: Application is currently under review; WeChat Pay is reviewing the sub-merchant's onboarding application. Please wait. Check the sub-merchant's status every other day until it changes.
REJECTED: It has been rejected; the sub-merchant's onboarding application has been rejected by WeChat Pay. Please check the reason for rejection in the application_rejected_detail field.
Example: UNDER_REVIEW

Sub-merchant onboarding application rejection details

application_reject_detail

object

BodyReturned when the sub-merchant's onboarding status is "REJECTED"; reason why the onboarding application is rejected by WeChat Pay reviewer; presented in json array format for every rejected field and the reason.
If the application is rejected, please log in to the WeChat Pay Merchant Platform, modify the application information as required, and resubmit (API is not supported for now).

Name	Variable Name	Type	Required	Description
Rejected field	field	string[1,128]	No	Name of the field rejected by WeChat Pay reviewer in the sub-merchant onboarding application form Example: name
Reason for rejection	reason	string[1,1024]	No	Reason for the rejection of the field in sub-merchant onboarding application form by the WeChat Pay reviewer Example: Merchant name is invalid.

pack up

Response for failed request:

Name

Variable Name

Type

Required

Description

Returned status code

code

string[1,32]

Yes

Error code. See the error code list for the enumerated values.

Returned information

message

string[1,256]

Yes

Returned message. It indicates the reason for the error if not empty.

Detailed error description

detail

object

It is returned when code is PARAM_ERROR. Details will be described below.

Name	Variable Name	Type	Required	Description
The location of incorrect parameter	field	string[1,256]	Yes	If the incorrect parameter is in the JSON for request body, it is populated with the JSON Pointer pointing to this parameter. If the incorrect parameter is in the request URL or querystring, it is populated with the variable name of this parameter.
Value of the incorrect parameter	value	string[1,256]	Yes	Value of the incorrect parameter
Cause of error	issue	string[1,256]	Yes	Cause of error
Location of the incorrect parameter	location	string[1,256]	No	body: The incorrect parameter is in the JSON for request body url: The incorrect parameter is in the request URL query: The incorrect parameter is in the querystring of the request

pack up

Response Example:

sub-merchant's status is "OPERATING" sub-merchant's status is "INCOMPLETE_APPLICATION"

{
  "sub_mchid": "20000100",
  "name": "test mcherchan_name",
  "shortname": "mcherchan_name",
  "office_phone": "075586010000",
  "merchant_introduction": "hotel and restaurant",
  "business_category": 644,
  "contact": {
    "name": "Bob Zhang",
    "phone": "+8613633334444"
  },
  "principal": {
    "principal_name": "Bob",
    "principal_id_number": "5555-8888"
  },
  "h5_payment": {
    "h5_authorization_state": "APPROVED"
  },
  "sub_merchant_state": {
      "sub_merchant_status": "OPERATING"
  }
}

{
  "sub_mchid": "20000100",
  "name": "test mcherchan_name",
  "shortname": "mcherchan_name",
  "office_phone": "075586010000",
  "merchant_introduction": "hotel and restaurant",
  "business_category": 644,
  "contact": {
    "name": "Bob Zhang",
    "phone": "+8613633334444"
  },
  "principal": {
    "principal_name": "Bob",
    "principal_id_number": "5555-8888"
  },
  "h5_payment": {
    "h5_authorization_state": "UNDER_REVIEW"
  },
  "sub_merchant_state": {
    "application_reject_detail": [
      { "field": "name", "reason": "Merchant name is invalid." }
    ],
    "application_status": "REJECTED",
    "sub_merchant_status": "INCOMPLETE_APPLICATION"
  }
}

5. Error Codes

Error Message	Description	Solution
PARAM_ERROR	Req param error	For the specific parameter format, please see the relevant document.
INVALID_REQUEST	Invaild request	Check your program based on the error message returned by the API.
SYSTEM_ERROR	System error please try again	System error. Re-initiate with the original parameters.

Language

Page Navigation

WeChat Pay

Feedback

Feedback

Submitted successfully

Feedback

Network exception, please try again later

Payments

Funding Products

Other Products

Query Sub-merchant API

1. API Intro

2. Request Parameters

Request Eample：

3. encryption guide

4. Response Parameters

Response for successful request:

Response for failed request:

Response Example:

5. Error Codes