alipay.overseas.secmerchant.offline.maintain
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
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.
|
contact_way String(256) | Phone number of the taxi driver. Note: +, -, numbers, and spaces are supported.
|
contact_person String(64) Required | Taxi driver name
|
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.
|
sign_type String | Sign type. RSA, RSA2 and MD5 are supported. Use uppercase.
|
sign String | Sign value
|
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.
|
result_code String | Processing result of the request. This field is returned only when the is_success field is T.
|
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×tamp=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®istration_no=1314520®ister_country=US®ister_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×tamp=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®istration_no=1314520®ister_country=US®ister_address=3 Old Concord Rd%2C Burlington%2C MA 01803&shareholder_name=mika&shareholder_id=3428000000000000&contact_no=%2B8618688888888&sign=7daf7f81bbfb77037bb3d6a5b177725f
Response
Request succeeds:
<?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:
<?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 |