Query Sub-merchant

Update Time：2025.01.08

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

Path parameter is a path parameter.

Query parameter needs to be passed in the request URL.

Body parameter needs to be passed in the request JSON.

2. Request Parameters

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

Request Example：

URL

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

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

Contact information

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

Business information

Director information

director

object

Director information,
The detail is listed below

Director information

Principal information

principal

object

Principal information,
The detail is listed below

Principal information

H5 payment application details

h5_payment

object

H5 payment application detail

H5 payment application details

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

Body Returned 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).

Sub-merchant onboarding application rejection details

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.

Detailed error description

Response Example:

sub-merchant's status is "OPERATING"

1{
2  "sub_mchid": "20000100",
3  "name": "test mcherchan_name",
4  "shortname": "mcherchan_name",
5  "office_phone": "075586010000",
6  "merchant_introduction": "hotel and restaurant",
7  "business_category": 644,
8  "contact": {
9    "name": "Bob Zhang",
10    "phone": "+8613633334444"
11  },
12  "principal": {
13    "principal_name": "Bob",
14    "principal_id_number": "5555-8888"
15  },
16  "h5_payment": {
17    "h5_authorization_state": "APPROVED"
18  },
19  "sub_merchant_state": {
20      "sub_merchant_status": "OPERATING"
21  }
22}

sub-merchant's status is "INCOMPLETE_APPLICATION"

1{
2  "sub_mchid": "20000100",
3  "name": "test mcherchan_name",
4  "shortname": "mcherchan_name",
5  "office_phone": "075586010000",
6  "merchant_introduction": "hotel and restaurant",
7  "business_category": 644,
8  "contact": {
9    "name": "Bob Zhang",
10    "phone": "+8613633334444"
11  },
12  "principal": {
13    "principal_name": "Bob",
14    "principal_id_number": "5555-8888"
15  },
16  "h5_payment": {
17    "h5_authorization_state": "UNDER_REVIEW"
18  },
19  "sub_merchant_state": {
20    "application_reject_detail": [
21      { "field": "name", "reason": "Merchant name is invalid." }
22    ],
23    "application_status": "REJECTED",
24    "sub_merchant_status": "INCOMPLETE_APPLICATION"
25  }
26}

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.