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

      registration

      Use the registration API to register a secondary merchant with Alipay.

      Structure

      A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see: 


      Note: Set the data type of each field (except array) as String. This means that you must use double quotation marks (" ") to enclose the field value. Examples:

      • If the data type of a field is Integer and its value is 20, set it as "20". 
      • If the data type of a field is Boolean and its value is true, set it as "true". 

      Request parameters

      registrationRequestId StringRequired

      The unique ID used to identify a registration request. 

      More information about this field:

      • This field is an API idempotency field. Merchant uses the registrationRequestId field for idempotency control. For registration requests that are initiated with the same value of registrationRequestId and reach a final status (S or F), the same result is to be returned for the request.
      • Maximum length: 64 characters
      registrationNotifyUrl URLOptional

      The URL provided by a merchant to receive the registration notification.  

      passThroughInfo StringOptional

      A key-value structure that is only used for site transparent data transmission. 

      More information about this field:

      • Maximum length: 2048 characters
      merchantInfo MerchantRegistrationInfoRequired

      Merchant information

      referenceMerchantId StringRequired

      The secondary merchant ID that is assigned by the acquirer.

      More information about this field:

      • Maximum length: 64 characters
      merchantDisplayName StringOptional

      The display name of the merchant

      More information about this field:

      • Maximum length: 64 characters
      merchantMCC StringRequired

      Merchant category code, which is a four-digit number listed in MCC codes. 

      More information about this field:

      • Maximum length: 32 characters
      merchantAddress AddressOptional

      The address where the merchant business is registered.

      region StringRequired

      The two-character ISO 3166 country/region code

      More information about this field:

      • Maximum length: 2 characters
      state StringOptional

      State, county or province

      More information about this field:

      • Maximum length: 8 characters
      city StringOptional

      City, district, suburb, town, or village

      More information about this field:

      • Maximum length: 32 characters
      address1 StringOptional

      Address line 1 (such as street, PO Box, or company name)

      More information about this field:

      • Maximum length: 256 characters
      address2 StringOptional

      Address line 2 (such as apartment, suite, unit, or building)

      More information about this field:

      • Maximum length: 256 characters
      zipCode StringOptional

      ZIP or postal code

      More information about this field:

      • Maximum length: 32 characters
      label StringOptional

      Label for address, such as company or home

      More information about this field:

      • Maximum length: 64 characters
      registrationDetail RegistrationDetailRequired

      Detailed registration information

      legalName StringRequired

      The legal name that is used in the registration.

      More information about this field:

      • Maximum length: 256 characters
      attachments Array<Attachment>Optional

      The attachments submitted 

      attachmentType StringRequired

      The attachment type. Valid values are:

      • ARTICLES_OF_ASSOCIATION: Articles of association
      • ENTERPRISES_ANNUAL_INSPECTION_REPORT: Enterprise annual inspection report
      • PROOF_OF_ADDRESS: The proof of address
      • REGISTRATION_CERTIFICATE: Registration certificate
      file StringRequired

      The attactment file

      More information about this field:

      • Maximum length: 1024 characters
      attachmentName StringOptional

      The name of the attachment

      More information about this field:

      • Maximum length: 128 characters
      contactInfo Array<ContactInfo>Optional

      The company contact information

      contactNo StringRequired

      Contact number, such as mobile phone number. Email address can also be used.

      More information about this field:

      • Maximum length: 64 characters
      contactType StringRequired

      Contact type. Valid values are: 

      • MOBILE_PHONE: Mobile phone
      • TELEPHONE: Telephone
      • EMAIL: Email
      registrationType StringRequired

      The registration type. Valid values are:

      • ENTERPRISE_REGISTRATION_NO: Merchant registration ID
      • INDEPENDENT_CONTRACTOR_LICENSE_NO: The license number of ride-share driver or taxi driver.
      • OTHER_IDENTIFICATION_NO: Other registration type.
      • US_FEDERAL_EIN:(Employer Identification Number) EIN of USmerchant
      registrationNo StringRequired

      The company registration number

      More information about this field:

      • Maximum length: 64 characters
      registrationAddress AddressRequired

      The company registration address

      region StringRequired

      The two-character ISO 3166 country/region code

      More information about this field:

      • Maximum length: 2 characters
      state StringOptional

      State, county or province.

      More information about this field:

      • Maximum length: 8 characters
      city StringOptional

      City, district, suburb, town, or village.

      More information about this field:

      • Maximum length: 32 characters
      address1 StringOptional

      Address line 1 (such as street, PO Box, or company name)

      More information about this field:

      • Maximum length: 256 characters
      address2 StringOptional

      Address line 2 (such as apartment, suite, unit, or building)

      More information about this field:

      • Maximum length: 256 characters
      zipCode StringOptional

      ZIP or postal code

      More information about this field:

      • Maximum length: 32 characters
      label StringOptional

      Label for address, such as company or home

      More information about this field:

      • Maximum length: 64 characters
      businessType StringRequired

      The business type. Valid values are:

      • ENTERPRISE: The business type is enterprise.
      • INDIVIDUAL: The business type is individual.
      registrationEffectiveDate DatetimeOptional

      The date when the business registration is in effective. 

      More information about this field:

      • The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:30".
      registrationExpireDate DatetimeOptional

      The date when the business registration expires.

      More information about this field:

      • The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:30".
      websites Array<WebSite>Optional

      Merchant websites

      name StringOptional

      The name of the website

      More information about this field:

      • Maximum length: 256 characters
      url URLRequired

      The URL of the website

      More information about this field:

      • Maximum length: 2048 characters
      desc StringOptional

      The description of the website

      More information about this field:

      • Maximum length: 512 characters
      logo LogoOptional

      Merchant logo

      logoName StringRequired

      The logo name

      More information about this field:

      • Maximum length: 12 characters
      logoUrl URLOptional

      The logo URL

      More information about this field:

      • Maximum length: 2048 characters
      productCodes StringRequired

      Product codes. For online payments, the valid values of this field are:

      productCodes: ["CASHIER_PAYMENT", "AGREEMENT_PAYMENT"]

      Response parameters

      result ResultRequired

      The request result contains information such as status and error codes.

      resultCode StringRequired

      Result code

      More information about this field:

      • Maximum length: 64 characters
      resultStatus StringRequired

      Result status. Valid values are: 

      • S: Successful 
      • F: Failed 
      • U: Unknown

      More information about this field:

      • Maximum length: 2 characters
      resultMessage StringOptional

      Result message that describes resultCode in detail.

      More information about this field:

      • Maximum length: 256 characters
      passThroughInfo StringOptional

      A key-value structure that is only used for site transparent data transmission. 

      More information about this field:

      • Maximum length: 2048 characters

      More information

      See the following list for important details on the main parameters:

      • For a secondary merchant registration request, merchantId and referanceMerchantId must be globally unique. If the registration is repeated, an error of REPEAT_REGISTRATION is returned.
      • If the type of field is Enum, the value of field must be a value within the specified range of Enum. For example, attachmentType, contactType, registrationType, businessType and productCodes are of the enum type. If the value passed in is outside Enum, an error of PARAM_ILLEGAL is returned.
      • If the Required field is not passed in, an error of PARAM_ILLEGAL is returned.
      • For String type fields, if the parameter length exceeds the specified maximum length or is less than the minimum length, an error of PARAM_ILLEGAL is returned.
      • The url of website must be a valid URL, otherwise an error of PARAM_ILLEGAL will be returned.
      • The address must be an address that can be recognized by Google Maps.
      • merchantInfo.registrationDetail.attachments.file must be a URL that a file can download.
      • For merchantInfo.merchantMCC values, see MCC List for details. 

      Error codes

      Error codes are usually classified into the following categories:

      • Common error codes: common for all online and in-store payment APIs.
      • API-specific error codes: listed in the following table.  

      Result/Error codes

      CodeValueMessageFurther action
      SUCCESSSSuccess

      The registration is successful, no further action is needed.

      INVALID_CLIENTFThe client is invalid.

      Check whether the clientId is correct.

      MEDIA_TYPE_NOT_ACCEPTABLEFThe server does not implement the media type that is acceptable to the client.

      Check whether the media type is correct.

      METHOD_NOT_SUPPORTEDFThe server does not implement the requested HTTP method.

      Check whether the HTTP method is correct.

      REPEAT_REQ_INCONSISTENTFRepeated requests are inconsistent.

      Change registrationRequestId and call the interface again.

      REGISTRATION_UNDER_REVIEWFA previously submitted registration is currently under review. No new registration or modification is allowed.

      The submitted registration is currently under review. Please wait for the final result.

      REPEAT_REGISTRATIONFRepeated registration for merchant

      Prompt the user not to register repeatedly.

      Request/Response Code

      Request

      Method

      POST

      Endpoint

      /v1/merchants/registration

      Header

      Accept: application/json

      URL

      Domain name

      Request Body
      Request parameters
      Response Body
      Body content