alipay.overseas.secmerchant.online.maintain

Call this interface to register secondary merchants of online payments into Alipay system, or to update the registration information of secondary merchants.

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.online.maintain

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 is 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 request. The time is in GMT+8, and in a format of yyyy-MM-dd HH:mm:ss.By default, the request expires in 30 minutes.

Example:2012-12-21 17:11:16

Business parameter

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_id

String(64) Required

The unique ID assigned by the partner to identify a secondary merchant. The ID can contain letters, numbers, and underscores. 

Example:63472327348

secondary_merchant_industry

String(4) Required

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

.

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:HK

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

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"}]

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

registration_no

String(128)Required

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

shareholder_name

String(64)

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(64)

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_id

String(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)Required

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

Example:+86139xxxx7893

contact_email

String(128)

Contact email address of the secondary merchantExample: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

Parameter

Description

site_type

String Required

Site type. For website URL, the value of this parameter must be WEB. For app download URL, the value of this parameter must be APP. Use uppercase. 

Example:WEB

site_url

String(256) Required

Site URL. When site_type is WEB, pass the URL in this format: http/https + SLD + TLD. When site_type is APP, pass the APP download URL starting with http/https.

Example:https://www.alipay.com, https://itunes.apple.com/cn/app/id333206289

site_name

String(512)

Site name 

Example:xx Store

Notes:

  • If the parameter with String type has no length limitation, the Alipay system will not check the length of this parameter.
  • Do not use halfwidth quotation mark (") in parameter values.

Response

Sync response

The response is in XML format.

Parameter

Description

Basic parameter

is_success

String Required

Indicates whether the request succeeds or not, with a value of T for success and F for failure. Note: a successful request does not mean the business is accepted and processed successfully. 

Example:T

sign_type

String

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

Example:MD5

sign

String

Sign value 

Example:3afc92ac4708425ab74ecb2c4e58ef56

error

String

Error code that is returned when the request is failed to describe the request failure reason. For more information, see the Error Code section in this document.

Example:PARAM_ILLEGAL

result_code

String

Processing result of the request. This field is returned only when the is_success field is T.

Example:SUCCESS

Note:

The synchronous response might have more parameters due to the upgrade on the Alipay server side. You can ignore parameters that are not included in this API document. 

Samples

Request

A sample for the request with secondary_merchant_type being INDIVIDUAL:

https://intlmapi.alipay.com/gateway.do?service=alipay.overseas.secmerchant.online.maintain&partner=2088021017666931&_input_charset=UTF-8&sign_type=MD5&timestamp=2019-09-04%2000%3A00%3A12&secondary_merchant_name=Mika's%20coffee%20shop&secondary_merchant_id=1314520&secondary_merchant_industry=5499&register_country=US&register_address=3%20Old%20Concord%20Rd%2C%20Burlington%2C%20MA%2001803%E7%BE%8E%E5%9B%BD&site_infos=%5B%7B%22site_type%22%3A%22WEB%22%2C%22site_url%22%3A%22https%3A%2F%2Fwww.mikascoffee.com%22%2C%22site_name%22%3A%22mikascoffee%22%7D%5D&secondary_merchant_type=INDIVIDUAL&registration_no=1314520&shareholder_name=mika&shareholder_id=3428000000000000&contact_no=%20%2B8618688888888&sign=de8b5c5fafc4fe81a862f76f22d5bf58

A sample for the request with secondary_merchant_type being ENTERPRISE:

https://intlmapi.alipay.com/gateway.do?service=alipay.overseas.secmerchant.online.maintain&partner=2088021017666931&_input_charset=UTF-8&sign_type=MD5&timestamp=2019-09-04%2000%3A00%3A12&secondary_merchant_name=Mika's%20coffee%20shop&secondary_merchant_id=1314520&secondary_merchant_industry=5499&register_country=US&register_address=3%20Old%20Concord%20Rd%2C%20Burlington%2C%20MA%2001803%E7%BE%8E%E5%9B%BD&site_infos=%5B%7B%22site_type%22%3A%22WEB%22%2C%22site_url%22%3A%22https%3A%2F%2Fwww.mikascoffee.com%22%2C%22site_name%22%3A%22mikascoffee%22%7D%5D&secondary_merchant_type=ENTERPRISE&registration_no=1314520&representative_name=mika&representative_id=3428000000000000&contact_no=%20%2B8618688888888&sign=d9a2d1d1004377b70db6f4ce5ad55a40

Response

Request succeeds and the registration succeeds:

copy
<?xml version="1.0" encoding="utf-8"?>
<alipay>
<is_success>T</is_success>
<request>
    <param name="secondary_merchant_industry">5935</param>
    <param name="_input_charset">UTF-8</param>
    <param name="sign">8457f906bf89a5e444a6e5c28f8da499</param>
    <param name="site_infos">
        [{"site_type":"WEB","site_url":"https://alipay.com","site_name":"websit"}]
    </param>
    <param name="secondary_merchant_id">100xxxxx0031</param>
    <param name="register_address">No.278, Road YinCheng, Shanghai, China</param>
    <param name="partner">208xxxxxxxxx2823</param>
    <param name="service">alipay.overseas.secmerchant.online.maintain</param>
    <param name="secondary_merchant_name">Alipay (China) Network Technology Co., Ltd</param>
    <param name="register_country">HK</param>
    <param name="sign_type">MD5</param>
    <param name="timestamp">2018-10-09 16:04:16</param>
    <param name="secondary_merchant_type">INDIVIDUAL</param>
    <param name="registration_no">012345678</param>
    <param name=“representative_name”>Tom Li</param>
    <param name=“representative_id”>123456789 Li</param>
    <param name="settlement_no">2600100000</param>
    <param name="contact_no">+86139xxxx7893 </param>
    <param name="contact_email">tomli@gmail.com </param>
</request>
<response>
    <alipay>
        <result_code>SUCCESS</result_code>
    </alipay>
</response>
<sign>744a87f0e3b40e6a8cd8f9705ce61511</sign>
<sign_type>MD5</sign_type>
</alipay>

Request succeeds but the registration fails:

copy
<alipay>
    <is_success>F</is_success>
    <error>PARAM_ILLEGAL</error>
    <sign>ba101b7ffb43afde9ba63c0de335218e</sign>
    <sign_type>MD5</sign_type>
</alipay>

Request fails or the access data are wrong:

copy
<?xml version="1.0" encoding="utf-8"?>
<alipay>
    <is_success>F</is_success>
    <error>ILLEGAL_PARTNER</error>
</alipay>

Error codes

Business logic errors

Returned result

Description

MCC_CAN_NOT_MODIFY

The MCC passed in cannot match the original MCC. Please ensure that the passed MCC is the original MCC.

REGISTER_COUNTRY_FORBIDDEN

For anti-money laundering reasons, the country or region in register_country cannot be registered.

PARAM_ILLEGAL

The parameter is illegal. The parameter is too long, parameter format is wrong, or a required parameter is not passed. Please check and rectify the parameter according to the API document.

SYSTEM_ERROR

Alipay system error

DUPLICATE_REQUEST

Duplicate request submitted. The previous registration request is still in process.

MERCHANT_TYPE_ILLEGAL

Illegal secondary merchant type. The value of the secondary_merchant_type field can only be ENTERPRISE or INDIVIDUAL. 

BUSINESS_NAME_UPDATE_FORBIDDEN

The secondary_merchant_name field cannot be updated because the business name is not allowed to be updated.

REGISTRATION_NO_UPDATE_FORBIDDEN

The registration_no field cannot be updated because the registration number is not allowed to be updated.

REGISTER_COUNTRY_UPDATE_FORBIDDEN

The register_country field cannot be updated because the registration country is not allowed to be updated.

MERCHANT_TYPE_UPDATE_FORBIDDEN

The secondary_merchant_type field cannot be updated because the merchant type is not allowed to be updated.

REPRESENTATIVE_NAME_UPDATE_FORBIDDEN

The representative_name field cannot be updated because the representative name is not allowed to be updated.

REPRESENTATIVE_ID_UPDATE_FORBIDDEN

The representative_id field cannot be updated because the representative ID is not allowed to be updated.

Access errors

Returned result

Description

ILLEGAL_SIGN

Illegal signature

ILLEGAL_DYN_MD5_KEY

Dynamic key information is incorrect

ILLEGAL_ENCRYPT

Encryption is incorrect

ILLEGAL_ARGUMENT

Incorrect parameter

ILLEGAL_SERVICE

Service Parameter is incorrect

ILLEGAL_USER

User ID is incorrect

ILLEGAL_PARTNER

Incorrect Partner ID

ILLEGAL_EXTERFACE

Interface configuration is incorrect

ILLEGAL_PARTNER_EXTERFACE

Partner's interface information is incorrect

ILLEGAL_SECURITY_PROFILE

Matching private key configuration is not found

ILLEGAL_AGENT

Agency ID is incorrect

ILLEGAL_SIGN_TYPE

The signature type is incorrect

ILLEGAL_CHARSET

The character set is illegal

HAS_NO_PRIVILEGE

Has no right to visit

INVALID_CHARACTER_SET

The character set is invalid

System errors

When system error occurs, please contact Global Merchant Technical Support (AlipayGlobalTechService@service.alipay.com).

Returned result

Description

SYSTEM_ERROR

Alipay system error

SESSION_TIMEOUT

Session timeout

ILLEGAL_TARGET_SERVICE

Wrong target service

ILLEGAL_ACCESS_SWITCH_SYSTEM

Merchant is not allowed to visit system of this type

EXTERFACE_IS_CLOSED

The interface is closed