Onboarding
The marketplace can onboard sub-merchants to enable payment, settlement, and other funding services. The sub-merchant onboarding process is shown in the figure below:
Figure 1. Onboarding flow of sub-merchant
- Sub-merchant provides the onboarding materials to the marketplace.
- The marketplace helps sub-merchant settle in Antom by calling register API to submit relevant materials.
- Antom returns the result of the onboarding application to the marketplace.
- The marketplace returns the result of the onboarding application to the sub-merchant.
- After the marketplace submits the sub-merchant onboarding materials, Antom enters into the materials review process, which takes 4 to 17 days.
- Once the material review is completed, Antom sends an asynchronous notification to inform the marketplace of the sub-merchant onboarding result.
- The marketplace informs the result to sub-merchant.
Application for onboarding
The marketplace applies for sub-merchant onboarding by calling the register API. The application requires the following materials to be provided:
- Settlement information: Settlement-related information such as the settlement bank account of the sub-merchant.
- Merchant identity: Entity information of the sub-merchant.
- Entity information: Entity information and related information of the sub-merchant.
- Business information: Business-related information such as exhibition websites and types of products sold.
Settlement information
In the API request, the marketplace needs to input the settlement bank account (settlementBankAccount), account supporter, and other relevant information, as well as the settlement currency (settlementCurrency) corresponding to the settlement bank account.
{
"//": "...",
"settlementInfos": [
{
"settlementBankAccount": {
"bankRegion": "BR",
"bankAccountNo": "1234567",
"swiftCode": "AAAAAABRAAA",
"accountHolderName": "Timi",
"routingNumber": "123",
"bankBranchCode": "0001",
"cardTIN": "1234567****",
"depositType": "CC",
"accountHolderType": "ENTERPRISE"
},
"settlementCurrency": "USD"
}
],
"//": "...",
}Merchant identity
In merchantInfo, the marketplace needs to define referenceMerchantId of the sub-merchant, which will be used in payment and settlement requests. loginId will be used as the sub-merchant's Antom account for registering the email address. The sub-merchant can use this email to log in to the Antom Merchant Portal backend.
legalEntityType under merchantInfo indicates the entity type of the sub-merchant. Currently, only company-type entities are supported to settle in.
{
"//": "...",
"merchantInfo": {
"loginId": "a_cangxi_lj_20230611_205925_260@test****",
"legalEntityType": "COMPANY",
"company": "...",
"entityAssociations": "...",
"businessInfo": "...",
"referenceMerchantId": "mid_cangxi_lj_20230611_205925****"
}
}Entity information
If the entity type of the sub-merchant is a company, the marketplace needs to upload the company information in the onboarding request via merchantInfo.company, and its association information via merchantInfo.entityAssociations.
In the company information of the sub-merchant, the marketplace needs to upload the association's articles and confirmation letter of authorized signatory through merchantInfo.company.attachments, together with the corresponding file download address in fileUrl. If the company is listed, the marketplace needs to upload its listing information via stockInfo.
Antom defines two categories of sub-merchant's related entities as legal representatives and shareholders, which need the marketplace to upload both in the request. For shareholders, the marketplace needs to upload their shareholding ratio via shareholdingRatio.
{
"//": "...",
"merchantInfo": {
"loginId": "20230706_212932_137@test****",
"legalEntityType": "COMPANY",
"company": {
"legalName": "Tom and Jerry",
"registeredAddress": {
"region": "BR"
},
"attachments": [
{
"attachmentType": "SIGNATURE_AUTHORIZATION_LETTER",
"fileUrl": "https://img.alicdn.com/tps/TB1h9xxIFXXXXbKXXXXXXXXXXXX.jpg"
},
{
"attachmentType": "ARTICLES_OF_ASSOCIATION",
"fileUrl": "https://img.alicdn.com/tps/TB1sXGYIFXXXXc5XpXXXXXXXXXX.jpg"
}
],
"certificates": [
{
"certificateNo": "cnpj12****",
"certificateType": "CNPJ"
}
],
"companyType": "LTDA",
"incorporationDate": "2022-02-02",
"operatingAddress": {
"region": "BR"
}
},
"entityAssociations": [
{
"individual": {
"legalName": "Tom",
"certificates": [
{
"fileUrls": [
"https://img.alicdn.com/tps/TB1sXGYIFXXXXc5XpXXXXXXXXXX.jpg"
],
"certificateNo": "cpf12****",
"certificateType": "CPF"
}
],
"dateOfBirth": "1995-04-13"
},
"associationType": "LEGAL_REPRESENTATIVE",
"legalEntityType": "INDIVIDUAL"
},
{
"individual": {
"legalName": "Jerry",
"certificates": [
{
"certificateNo": "cpf12****",
"certificateType": "CPF"
}
],
"dateOfBirth": "1995-03-14"
},
"shareholdingRatio": "23.33",
"associationType": "UBO",
"legalEntityType": "INDIVIDUAL"
},
{
"//": "..."
}
]
}
}Business information
The marketplace needs to upload the business information of this sub-merchant via businessInfo, including exhibition websites and its business type MCC. Refer to MCC codes.
{
"//":"...",
"merchantInfo": {
"//":"...",
"businessInfo": {
"websites": [
{
"name": "homepage",
"description": "company's homepage url",
"url": "https://taobao.com"
}
],
"mcc": "5021"
},
"//":"..."
}
}Application result
After the marketplace submits the sub-merchant's onboarding request, Antom returns the submission result of this request, as shown in the following example:
{
"result": {
"resultStatus": "S",
"resultCode": "SUCCESS",
"resultMessage": "success."
},
"registrationStatus": "PROCESSING"
}If resultStatus is S, the registration request is submitted successfully, if it is F, the request is failed. Antom will show the failure reason through resultMessage. The registration status of sub-merchant returned by this API through registrationStatus is fixed to PROCESSING. This is because, once the onboarding application is submitted, Antom needs to review the onboarding materials.
Obtain notification of onboarding result
Once the onboarding request is submitted, Antom will review the provided materials. After the review is complete, Antom will communicate the result of the sub-merchant's onboarding to the marketplace through the notifyRegistration asynchronous notification API.
The marketplace must set the asynchronous notification address by editing Notification URL under the Integration Settings tab in Antom Dashboard.
The following is an example of an asynchronous notification of successful onboarding:
{
"notifyType": "REGISTRATION_RESULT",
"referenceMerchantId": "MERCHANT_2023061813584****",
"registrationRequestId":"REQUEST_2023061813584****",
"registrationStatus":"SUCCESS"
}If the onboarding fails, the onboarding failure reason is informed in reasonCode and reasonMessage in the asynchronous notification. The marketplace can change information according to the reason prompt and re-initiate the onboarding request. If the onboarding fails, loginId and referenceMerchantId will not be occupied and can be reused, but registrationRequestId needs to be replaced.
The following is an example of an asynchronous notification of failed onboarding:
{
"notifyType": "REGISTRATION_RESULT",
"referenceMerchantId": "MERCHANT_2023061813584****",
"registrationRequestId": "REQUEST_2023061813584****",
"registrationStatus": "FAIL",
"reasonCode": "MISSING_OR_INCORRECT_INFO",
"reasonMessage": "The registration information is incomplete or incorrect. Use a new registrationRequestId to call the register API again."
}Return the following message with fixed values to Antom after receiving the notification. If no such message is returned to Antom due to operation issues or network issues, Antom will send the notification again within 24 hours. The notification will be resent up to eight times or terminated after receiving the correct response, with an interval of 0 sec, 2 min, 10 min, 10 min, 1 h, 2 h, 6 h, and 15 h.
{
"result": {
"resultStatus": "S",
"resultCode": "SUCCESS",
"resultMessage": "success."
}
}More references
If the sub-merchant's settlement bank account information changes, the marketplace can assist the sub-merchant in submitting a change request through the API. Refer to Update settlement information for more details.