Alipay, China's leading third-party online payment solutionAlipay, China's leading third-party online payment solution

      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

      ParameterDescription
      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 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: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, 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: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: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

      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.

      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)

      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

      shareholder_nationality

      String(2)

      Nationality of the primary shareholder, specified by a 2-letter code defined in ISO 3166. For more details about the 2-letter country code, see ISO 3166. Specify this field only when the secondary merchant type is ENTERPRISE.

      Example: CN

      representative_nationality

      String(2)

      Nationality of the legal representative, specified by a 2-letter code defined in ISO 3166. For more details about the 2-letter country code, see ISO 3166. Specify this field only when the secondary merchant type is INDIVIDUAL. This field is optional if the secondary merchant type is ENTERPRISE.

      Example: CN

      #site_infos

      ParameterDescription

      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

      Note:

      If parameters of String type have no length limitation, the system will not check their length.

      #Response

      #Synchronous response

      ParameterDescription
      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 resultDescription
      REGISTER_COUNTRY_FORBIDDENFor anti-money laundering reasons, the country or region in register_country cannot be registered.
      PARAM_ILLEGALThe 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_ERRORAlipay system error
      DUPLICATE_REQUESTDuplicate request submitted. The previous registration request is still in process.
      MERCHANT_TYPE_ILLEGALIllegal 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 resultDescription
      ILLEGAL_SIGNIllegal signature
      ILLEGAL_DYN_MD5_KEYDynamic key information is incorrect
      ILLEGAL_ENCRYPTEncryption is incorrect
      ILLEGAL_ARGUMENTIncorrect parameter
      ILLEGAL_SERVICEService Parameter is incorrect
      ILLEGAL_USERUser ID is incorrect
      ILLEGAL_PARTNERIncorrect Partner ID
      ILLEGAL_EXTERFACEInterface configuration is incorrect
      ILLEGAL_PARTNER_EXTERFACEPartner's interface information is incorrect
      ILLEGAL_SECURITY_PROFILEMatching private key configuration is not found
      ILLEGAL_AGENTAgency ID is incorrect
      ILLEGAL_SIGN_TYPEThe signature type is incorrect
      ILLEGAL_CHARSETThe character set is illegal
      HAS_NO_PRIVILEGEHas no right to visit
      INVALID_CHARACTER_SETThe character set is invalid


      #System errors

      Returned resultDescription
      SYSTEM_ERRORAlipay system error
      SESSION_TIMEOUTSession timeout
      ILLEGAL_TARGET_SERVICEWrong target service
      ILLEGAL_ACCESS_SWITCH_SYSTEMMerchant is not allowed to visit system of this type
      EXTERFACE_IS_CLOSEDThe interface is closed