alipay.overseas.secmerchant.maintain.queryStatus

2020-11-24 08:06

Call this interface to query the registration status of secondary merchants for online payments.

Request

Service address

Environment	HTTPS request URL
Production environment	https://intlmapi.alipay.com/gateway.do
Test environment	https://mapi.alipaydev.com/gateway.do

Request parameters

Parameter Description

Basic parameter

service

String Required

Interface name

Example:alipay.overseas.secmerchant.maintain.queryStatus

partner

String(16) Required

The partner ID that is assigned by Alipay to identify an Alipay account. The partner ID is composed of 16 digits and begins with 2088.

Example:2088*********662

_input_charset

String Required

The charset with which the request data are encoded. UTF-8, GBK, and GB2312 are supported.

Example:UTF-8

sign_type

String Required

Sign type. RSA, RSA2 and MD5 are supported. Use uppercase.

Example:MD5

sign

String Required

Sign value

Example:2118ac8fad6bc1d9e88a6cd017c18d37

timestamp

String Required

The time when the merchant server sends the request. The time is in GMT+8, with a format of yyyy-MM-dd HH:mm:ss. By default, the request expires in 30 minutes.

Example:2019-02-01 08:30:10

Business parameter

secondary_merchant_id

String(64) Required

The unique ID assigned by the partner to identify a secondary merchant. The ID can contain letters, numbers, and underscores, but special characters or spaces are not allowed. Note: It is strongly suggested to keep the value within 20 bytes, for the convenience of management.

Example:MERCHANT_ID_0003

payment_method

String Required

Payment method of the secondary merchant, the value is ONLINE_PAYMENT for online payments.

Example:ONLINE_PAYMENT

Response

Synchronous response

Parameter Description

sign

String

Sign value

Example:744a87f0e3b40e6a8cd8f9705ce61511

sign_type

String

Sign type. RSA, RSA2 and MD5 are supported. Use uppercase.

Example:MD5

secondary_merchant_id

String(64) Required

Example:MERCHANT_ID_0003

reject_reason

String

The reason that the merchant is not registered successfully. The reject reason might be one of the following items:

High risk merchant, registration reject.
For security reason, registration reject.

This field is required when status is FAILED.

Example:High risk merchant, registration reject.

payment_method

String Required

Payment method of the secondary merchant, the value is ONLINE_PAYMENT for online payments.

Example:ONLINE_PAYMENT

partner

String(16) Required

The partner ID that is assigned by Alipay to identify an Alipay account. The partner ID is composed of 16 digits and begins with 2088.

Example:2088*********662

secondary_merchant_name

String(64) Required

Registration legal name of the secondary merchant, which is shown in the wallet and reconciliation file to identify a secondary merchant.

Note: If the secondary merchant type is INDIVIDUAL, specify the full legal name of the business owner to this field.

Example:Alipay (China) Network Technology Co., Ltd

secondary_merchant_type

String Required

Secondary merchant type, the value can be INDIVIDUAL for the sole proprietorship or ENTERPRISE for the limited company, private company, partnership, limited liability partnership (LLP), limited liability company (LLC), S corporation (S Corp), C corporation (C Corp), trust, or nonprofit organization (NPO)

Example:INDIVIDUAL

secondary_merchant_industry

String(4) Required

Business category code of the secondary merchant. For more information about the business category code, see MCC list.

registration_no

String(128)

Business registration number specified on the business registration document.

Note: This field is not required when the secondary merchant type is INDIVIDUAL and no registration number exists.

Example:012345678

register_country

String(2) Required

Registration country of the secondary merchant, specified by a 2-letter code defined in ISO 3166. For more details about the 2-letter country code, see ISO 3166.

Example:US

register_address

String(256) Required

Business registration address specified on the business registration document. Use postal address format.

Example:No.278, Road YinCheng, Shanghai, China

shareholder_name

String(128)

Legal name of the primary shareholder of the secondary merchant. Specify this field only when the secondary merchant type is ENTERPRISE.

Example:Jack Li (if the shareholder is an individual), Alipay.com Co.,Ltd (if the shareholder is an enterprise)

shareholder_id

String(128)

ID or passport number, or business registration number of the primary shareholder of the secondary merchant. Specify this field only when the secondary merchant type is ENTERPRISE.

Example:G53453888 (if the shareholder is an individual), 012345678 (if the shareholder is an enterprise)

representative_name

String(128)

Full legal name of the business owner. Specify this field only when the secondary merchant type is INDIVIDUAL. This field is optional if the secondary merchant type is ENTERPRISE.

Example:Tom Li

representative_idString(128)

ID or passport number of the business owner. Specify this field only when the secondary merchant type is INDIVIDUAL. This field is optional if the secondary merchant type is ENTERPRISE.

Example:123456789

settlement_no

String(64)

Settlement bank account number of the secondary merchant. Use letters and numbers only.

Example:2600100000

contact_no

String(64)

Contact phone number of the secondary merchant, numbers and special characters +-() only

Example:+86139xxxx7893

contact_email

String(128)

Contact email address of the secondary merchant

Example:tomli@gmail.com

cs_no

String(64)

Customer service phone number of the secondary merchant, numbers and special characters +-() only

Example:0213355xxx89

cs_email

String(128)

Customer service email address of the secondary merchant

Example:customerservice@xxxcompany.com

site_infos

String Required

This field is in JSON format and can contain up to 5 website URLs or app download URLs. See site_infos for details.URLs in this field cannot be updated incrementally. To add or remove URLs, re-pass the value again.

Example:Secondary merchant website URL or app download URL. Format: [{"site_type":"WEB","site_url":"https://alipay.com","site_name":"websit"},{"site_type":"APP","site_url":"https://alipay.com","site_name":"websit"}]

status

String Required

The status of the latest registration or update.The value can be one of the following item:

SUCCESS: The latest registration or update succeeds.
UNDER_REVIEW: The latest registration is under review.
MODIFICATION_REVIEW: The latest update is under review.
FAILED: The latest registration or update is failed and the reject_reason field will be returned.

Example:SUCCESS

Error codes

Business logic errors

Returned result	Description
PARAM_ILLEGAL	Required parameters are not entered or illegal parameters are entered. The illegal parameter might be too long, or with incorrect format. Action: Enter the correct parameters and send the request again.
DATA_NOT_EXIST	No data exist for the queried secondary merchant because the merchant is not registered. Action: Register the secondary merchant to Alipay system before you query the registration status.
SYSTEM_ERROR	Alipay system error. Action: Try again later.

Samples

Request

https://intlmapi.alipay.com/gateway.do?service=alipay.overseas.secmerchant.maintain.queryStatus&partner=2088021017666931&_input_charset=UTF-8&sign_type=MD5&secondary_merchant_id=1314520&payment_method=ONLINE_PAYMENT&sign=9c1f5f948d9e7d3109f6558a375b62d3

Response

The request succeeds and the query result is returned:

copy
<?xml version="1.0" encoding="utf-8"?>
<alipay>
    <is_success>T</is_success>
<request>
    <param name="service">alipay.overseas.secmerchant.maintain.queryStatus</param>
    <param name="partner">2088101131367863</param>
    <param name=“_input_charset”>gbk</param>
    <param name="sign_type">MD5</param>
    <param name="sign">2118ac8fad6bc1d9e88a6cd017c18d37</param>
    <param name="timestamp">2019-02-01 08:30:10</param>
    <param name="secondary_merchant_id">MERCHANT_ID_0003</param>
    <param name="payment_method">ONLINE_PAYMENT</param>  
</request>
<response>
    <alipay>
        <secondary_merchant_id>MERCHANT_ID_0003</secondary_merchant_id>
        <status>UNDER_REVIEW</status>
        <payment_method>ONLINE_PAYMENT</payment_method>
        <partner_id>2088101142878662</partner_id>
        <secondary_merchant_name>Alipay (China) Network Technology Co., Ltd</secondary_merchant_name>
        <secondary_merchant_type>INDIVIDUAL</secondary_merchant_type>
        <secondary_merchant_industry>0742</secondary_merchant_industry>
        <registration_no>012345678</registration_no>
        <register_country>HK</register_country>
        <register_address>No.278, Road YinCheng, Shanghai, China</register_address>
        <shareholder_name>Jack Li</shareholder_name>
        <shareholder_id>G53453888</shareholder_id>
        <representative_name>Tom Wang</representative_name>
        <representative_id>3524674343326</representative_id>
        <settlement_no>2600100000</settlement_no>
        <contact_no>+86139xxxx7893</contact_no>
        <contact_email>tomli@gmail.com</contact_email>
        <site_infos>[{"site_type":"WEB","site_url":"https://alipay.com","site_name":"websit"}]</site_infos>
    </alipay>
</response>
<sign>744a87f0e3b40e6a8cd8f9705ce61511</sign>
<sign_type>MD5</sign_type>
</alipay>

Failed to get the query result:

copy
<?xml version="1.0" encoding="utf-8"?>
<alipay>
<is_success>F</is_success>
<error>DATA_NOT_EXIST</error>
<sign>744a87f0e3b40e6a8cd8f9705ce61511</sign>
<sign_type>MD5</sign_type>
</alipay>