alipay.overseas.secmerchant.offline.maintain

2020-10-30 03:18

Call this interface to register secondary merchants of in-store payments into Alipay system, or to update 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.offline.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, with 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 parameters for both acquirers and system integrators

secondary_merchant_name

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

store_id

String(64)

Required

The unique ID assigned by the partner to identify a store of a secondary merchant. For taxicabs and limousines (MCC 4121), use the license plate number.

Example:23372327348

store_name

String(256)

Required

Store name. For taxicabs and limousines (MCC 4121), use the license plate number.

Example:Apple store

store_country

String(2)

Required

Store registration country. A 2-letter code defined in ISO 3166.

Example:HK

store_address

String(330)

Required

Registered store address. Use postal address format.

Example:Store address

store_industry

String(4)

Required

A 4-digit MCC code of the store. See MCC list for details.

Example:4121

internal_store_photo

String(256)

URL of the store interior photo.

Example:http://testmerchant.com/

external_storefront_phot

String(256)

URL of the store exterior photo.

Example:URL

extend_params

String(1024)

Information about taxi drivers in the JSON format, with fixed JSON keys of operation_id, contact_way, and contact_person. When the first time you register a driver and specify 4121 to the store_industry parameter, this parameter must be provided, otherwise, an error of CATEGORY_NOT_SUPPORT_DRIVER is returned. For more information, see extend_params. Note: -The value of each operation_id must be unique. -This field cannot be updated after the first time you register a driver. -Up to 10 drivers can be entered with this parameter.

Example:[{"operation_id": "1000332", "contact_way": "138xxxx1232", "contact_person": "driverName1"}, {"operation_id": "1082943492", "contact_way": "158xxxx2232", "contact_person": "driverName2"}]

Business parameters for acquirers only

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

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.277, Road YinCheng, Shanghai, China

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)

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

Example:186xxxx0000

contact_emailString(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:952xx

cs_email

String(128)

Customer service email address of the secondary merchant

Example:customerservice@xxxcompany.com

#extend_params

When the value of store_industry is 4121, the extend_params field must be specified.

The extend_params field specifies the taxi driver information. Taxi driver information in JSON format uses operation_id, contact_way, and contact_person as JSON keys. Up to 10 drivers can be entered with this field.

Parameter Description

operation_id

String(64)

Required

Taxi driver ID. Use only numbers and letters. Note: The value of each operation_id must be unique. Specify this field the first time you register a driver, and you cannot add or update this field later.

Example:1082943492

contact_way

String(256)

Phone number of the taxi driver. Note: +, -, numbers, and spaces are supported.

Example:158xxxx2232

contact_person

String(64)

Required

Taxi driver name

Example:driverName2

Notes:

If the parameter with String type has no length limit, the Alipay system doesn't check the length of this parameter.
Do not use the halfwidth quotation mark (") in parameter values.

#Response

#Synchronous 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

Request sample for a store to register:

https://intlmapi.alipay.com/gateway.do?service=alipay.overseas.secmerchant.offline.maintain&partner=208xxxxxxxxx8155&_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&store_id=1993&store_name=Mika's%20coffee%20shop&store_country=US&store_address=3%20Old%20Concord%20Rd%2C%20Burlington%2C%20MA%2001803%E7%BE%8E%E5%9B%BD&store_industry=5499&internal_store_photo=https%3A%2F%2Fwww.mikascoffee%2Fimg_321323.jpg&external_storefront_photo=https%3A%2F%2Fwww.mikascoffee%2Fimg_321322.jpg&secondary_merchant_type=INDIVIDUAL&registration_no=1314520&register_country=US&register_address=3%20Old%20Concord%20Rd%2C%20Burlington%2C%20MA%2001803%E7%BE%8E%E5%9B%BD&shareholder_name=mika&shareholder_id=342xxxxxxxxx0000&contact_no=%2B8618688888888&sign=af2d1f166779562fae5dfb056daf7196

Request sample for a taxi to register:

https://intlmapi.alipay.com/gateway.do?service=alipay.overseas.secmerchant.offline.maintain&partner=208xxxxxxxxx8155&_input_charset=UTF-8&sign_type=MD5&timestamp=2019-09-04 00%3A00%3A12&secondary_merchant_name=Mika's coffee shop&secondary_merchant_id=1314520&store_id=3344&store_name=Mika's drive&store_country=US&store_address=3 Old Concord Rd%2C Burlington%2C MA 01803&store_industry=4121&extend_params=[{"operation_id"%3A"1000332"%2C"contact_way"%3A"138xxxxx1232"%2C"contact_person"%3A"Driver Li"}%2C{"operation_id"%3A"1000333"%2C"contact_way"%3A"13888881232"%2C"contact_person"%3A"Tom"}]&secondary_merchant_type=INDIVIDUAL&registration_no=1314520&register_country=US&register_address=3 Old Concord Rd%2C Burlington%2C MA 01803&shareholder_name=mika&shareholder_id=3428000000000000&contact_no=%2B8618688888888&sign=7daf7f81bbfb77037bb3d6a5b177725f

#Response

Request succeeds:

copy
<?xml version="1.0" encoding="utf-8"?>
<alipay>
    <is_success>T</is_success>
    <request>
        <param name="service">alipay.overseas.secmerchant.offline.maintain</param>
        <param name="partner">2088101142878662</param>
        <param name="_input_charset">UTF-8</param>
        <param name="sign_type">MD5</param>
        <param name="sign">2118ac8fad6bc1d9e88a6cd017c18d37</param>
        <param name="timestamp">2018-08-03 00:28:32</param>
        <param name="secondary_merchant_name">Alipay (China) Network Technology Co., Ltd</param>
        <param name="secondary_merchant_id">2015051446800462</param>
        <param name="store_id">23372327348</param>
        <param name="store_name">LV</param>
        <param name="store_country">HK</param>
        <param name="store_address">store address</param>
        <param name="store_industry">4121</param>
        <param name="secondary_merchant_type">INDIVIDUAL</param>
        <param name="registration_no">012345678</param>
        <param name="register_country">HK</param>
        <param name="register_address">No.277, Road YinCheng, Shanghai, China</param>
        <param name=“representative_name”>Tom Li</param>
        <param name=“representative_id”>123456789</param>
        <param name="settlement_no">2600100000</param>
        <param name="contact_no">186xxxx0000 </param>
        <param name="contact_email">support@xcompany.com </param>
    </request>
<response>
    <alipay>
        <result_code>SUCCESS</result_code>
    </alipay>
</response>
<sign>744a87f0e3b40e6a8cd8f9705ce61511</sign>
<sign_type>MD5</sign_type>
</alipay>

Request fails or the access data is incorrect:

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

#Error codes

#Business logic errors

Returned result	Description
MCC_CAN_NOT_MODIFY	The MCC passed in cannot match the original MCC. Action: Ensure that the passed MCC is the same as the original MCC.
MCC_TYPE_ILLEGAL	The MCC is invalid. Action: Modify the MCC type and then try again.
PARAM_ILLEGAL	The parameter is illegal. The parameter is too long, parameter format is wrong, or a required parameter is not passed. Action: Check and rectify the parameter according to the API document.
SYSTEM_ERROR	Alipay system error. Action: Try again later.
LBS_GEOGRAPHIC_INFORMATION_INVALID	The address cannot match the country/region, or the address cannot be located. Action: Ensure that the address is valid and use the address that can be located in Google map.
CATEGORY_NOT_SUPPORT_DRIVER	If the store_industry field is 4121, and the extend_params field is not passed when you send a request for the first time, this error is returned when you update the store information and pass the driver information. Action: When the store_industry field is 4121, the extend_params field must be specified.
DUPLICATE_REQUEST	Duplicate request submitted. The previous registration request is still in process. Action: Wait until the previous registration request completes.
MERCHANT_TYPE_ILLEGAL	Illegal secondary merchant type. The value of the secondary_merchant_type field can only be ENTERPRISE or INDIVIDUAL. Action: Enter the correct value for the secondary_merchant_type field.
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 Alipay Technical Support (overseas_support@service.alibaba.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