Register a merchant
In certain countries or regions, for legal or compliance reasons, the merchant information that is related to this payment must be registered before a payment can be processed.
Therefore, Alipay+ Acquiring Service Providers (ACQPs) might need to register a merchant, and then obtain the registration result by inquiring or receiving notifications from Alipay+.
To ensure ACQPs obtain these capabilities regarding merchant registration, Alipay+ provides the following three APIs:
- registration: This API is used by the ACQP to register a new merchant or update an existing registration.
- inquiryRegistrationStatus: This API is used by the ACQP to inquire about the merchant registration status from Alipay+.
- notifyRegistrationStatus: This API is used by Alipay+ to notify the ACQP of the merchant registration result.
This chapter explains how you can use these APIs to execute operations on merchant registration.
Workflow
The following figure illustrates the merchant registration flow:
Figure 1. Merchant registration flow
The merchant registration flow consists of the following steps:
- The ACQP sends the merchant registration request to Alipay+ by calling the registration API.
- Alipay+ returns the response to the ACQP. For different results, the ACQP takes different further actions as follows:
- If the result of the API call is unknown, the ACQP needs to send the request again until the API call failed or succeeds.
- If the API call failed, the ACQP needs to modify the request parameters and send the request again.
- If the API call succeeds, the ACQP can use the inquiryRegistrationStatus API to inquire about the registration status at regular intervals, or wait for notifications from Alipay+ by integrating the notifyRegistrationStatus API.
- For a merchant that has been registered, if the ACQP wants to add payment products, the ACQP needs to updates the value of the productCodes parameter in the registration API, and then calls the API again.
Register a merchant or update a registration
By calling the registration API, the ACQP can either register a new merchant or update an existing registration, such as modify merchant information and add payment products.
Processing logic
When using the registration API, the ACQP needs to take the following things into consideration:
- Batch operations are not supported. For a single time, only one merchant or store can be registered or updated.
- The response of the registration request only indicates the result of the API call, but does not indicate whether the registration is processed. For example, if result.resultStatus is
S
, it only means the registration request is successfully accepted, but does not mean the registration succeeds. - When calling a request to update an existing registration, check whether the last registration request is still within 7 natural days or processed. Only when the last request exceeds 7 natural days, or it is within 7 natural days but has been processed, can the new request be accepted; otherwise, it is rejected.
- The Mobile Payment Partner (MPP) returns registration results to Alipay+ asynchronously (normally within 7 natural days), and the ACQP can obtain registration results by calling the inquiryRegistrationStatus API. For more information, see Inquire about registration results.
- If the ACQP wants to receive notifications from Alipay+ of the registration result, the ACQP needs to integrate the notifyRegistrationStatus API and specify the value of the registrationNotifyUrl parameter in the registration API. For more information, see Receive notifications about registration results from Alpay+.
Sample
The ACQP sends the registration request to Alipay+.
{
"registrationRequestId": "2020091811058602000006001420000",
"merchantInfo": {
"referenceMerchantId": "2188120000190000",
"merchantDisplayName": "Example",
"merchantMCC": "5735",
"websites": [{
"url": "https://alipayplus.com",
"websiteType": "WEB"
}],
"registrationDetail": {
"legalName": "ExampleLegalName",
"registrationType": "ENTERPRISE_REGISTRATION_NO",
"registrationNo": "RN100",
"registrationAddress": {
"region": "CN",
"address1": "浙江省杭州市"
},
"businessType": "ENTERPRISE"
}
},
"productCodes": ["CASHIER_PAYMENT"]
}
Alipay+ returns the result to the ACQP.
{
"result": {
"resultCode": "SUCCESS",
"resultStatus": "S",
"resultMessage": "Success"
}
}
More information
For more information about how to use the API (such as the parameter description), see registration.
Inquire about registration results
The Mobile Payment Provider (MPP) returns registration results to Alipay+ asynchronously (normally within 7 natural days), and the ACQP can obtain registration results by calling the inquiryRegistrationStatus API.
Processing logic
When using the inquiryRegistrationStatus API, the ACQP needs to take the following things into consideration:
- The ACQP can call the API in a fixed frequency, for example, once a day, to obtain the latest registration status until all the MPPs return the registration results.
- The ACQP can query the registration result of the corresponding request by specifying the value of registrationRequestId, or query the registration result of the corresponding merchant by specifying the value of registrationMerchantId.
- In the response returned by Alipay+, the ACQP can check both the whole registration status of all the MPPs to be registered to, and the registration status of a certain MPP.
Sample
The ACQP sends the inquiry request to Alipay+.
{
"referenceMerchantId": "2188120000190000"
}
Alipay+ returns the result to the ACQP.
{
"result": {
"resultCode": "SUCCESS",
"resultStatus": "S",
"resultMessage": "Success"
},
"registrationResult": {
"registrationStatus": "COMPLETED"
},
"pspRegistrationResultList": [{
"productCodes": [
"CASHIER_PAYMENT"
],
"pspName": "ALIPAY_CN",
"registrationResult": {
"registrationStatus": "APPROVED"
}
}]
}
More information
For more information about how to use the API (such as the parameter description), see inquiryRegistrationStatus.
Receive notifications about registration results from Alipay+
If the ACQP wants to receive notifications from Alipay+ about registration results, the ACQP needs to integrate the notifyRegistrationStatus API. Each time Alipay+ receives a notification from the MPP, Alipay+ will notify the ACQP of the registration result by calling the API.
Processing logic
When using the notifyRegistrationStatus API, the ACQP needs to take the following things into consideration:
- The ACQP needs to specify the value of registrationNotifyUrl in the registration API to receive the notifications from Alipay+.
- For every unique registrationRequestId, Alipay+ returns a notification about the registration result.
- Each notification from Alipay+ contains the registration statuses of all the MPPs to be registered to.
Sample
Alipay+ sends the notification request to the ACQP.
{
"registrationRequestId": "2020091811058602000006001420000",
"referenceMerchantId": "2188120000190000",
"referenceStoreId": "340000",
"registrationResult": {
"registrationStatus": "COMPLETED"
},
"pspRegistrationResultList": [
{
"productCodes": [
"CASHIER_PAYMENT"
],
"pspName": "ALIPAY_CN",
"registrationResult": {
"registrationStatus": "APPROVED"
}
}
]
}
The ACQP returns the result to Alipay+.
{
"result": {
"resultCode": "SUCCESS",
"resultStatus": "S",
"resultMessage": "Success"
}
}
More information
For more information about how to use the API (such as the parameter description), see notifyRegistrationStatus.