registerCustomer
POST
: /aps/api/business/onboard/registerCustomer
Note: This interface is only used for transfers inbound to China. Do not call this interface when you send transfers to other countries.
Before the Partner can transfer funds to a new beneficiary, the Partner must register the beneficiary on WorldFirst(Alipay). Use the registerCustomer interface to submit the beneficiary information to WorldFirst(Alipay). WolrdFirst(Alipay) may need to validate the beneficiary before completing the registration process.
The Customer registration process is asynchronous. After submission, WorldFirst(Alipay) notifies the Partner about the acceptance of the registration request. For the final result of the registration, the Partner can:
- Query with the inquiryRegisterCustomer interface.
- Wait for notifications from WorldFirst(Alipay). WorldFirst(Alipay) notifies the partner about the registration result with the notifyRegisterCustomer interface.
Structure
A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see:
Request parameters
Field | Data type | Required | Description |
registerRequestId | String | Yes | The unique ID assigned by the Partner to identify a registration request of a beneficiary. Note:
More information:
|
customer | Customer object | Yes | Information of the beneficiary that is to be registered. |
products | Array<Product object> | Yes | The product that the customer contracts to use. |
accounts | Array<Account object> | Yes | Information of the customer's WorldFirst(Alipay) account. |
More information
The name of the merchant must be the same as the holder's name of the beneficiary's bank account.
- Merchant name varies depending on the type of the merchant:
customer.individual.certificates.holderName.fullName
(For individual merchants)customer.company.certificates.holderName.fullName
(For enterprise merchants)
- Considering the value of the
customer.user.userId
field:
- For global transfers: the value of userId is the same as
referenceCustomerId
. - For transfers inbound to China, the value of
userId
is assigned by WorldFirst(Alipay) since 2021.
Note: The contact address of the individual.contactAddress field is the same as the address on the ID card.
When there is UBO in a company with more than 25% shareholdings, the customer.businessPartner.individual.wealthSources
field is required.
Response parameters
Field | Data type | Required | Description |
result | Result object | Yes | Indicates whether this API is called successfully. |
customerId | String | Yes | The unique ID assigned by WorldFirst(Alipay) to identify a Customer. In this case, a beneficiary. More information:
|
referenceCustomerId | String | Yes | The unique ID assigned by the Partner to identify a Customer. In this case, a beneficiary. More information:
|
registerRequestId | String | Yes | The unique ID assigned by the Partner to identify a Customer registration request. More information:
|
registerDetail | RegisterDetail object | Yes | Information about the registration status. |
Result processing logic
After calling the API, a response is returned with two result codes, result.resultStatus
and registerDetail.registerStatus
.
result.resultStatus
indicates the result of the inquiry.registerDetail.registerStatus
field indicates the result of the Customer registration process.
- When the registration failed to pass the review,
registerDetail.reasonCode
isGMM_AUDITING_RECTIFY
. - The detailed reason is elaborated by the
auditDetails.auditReason
field. For more details aboutauditReason
, refer to the References section in the inquiryRegisterCustomer chapter.
After calling the API, a response is returned. The possible responses for result.resultStatus
are:
Result status | Description |
S | This indicates the API call succeeded. |
F | This indicates the API call failed. For more information on why the call failed, see |
U | This indicates the API call result is unknown. Call the interface again. If the issue is not resolved, contact WorldFirst(Alipay) Technical Support. |
Result codes
registerDetail.reasonCode
reasonCode | registerStatus | registerMessage | Further action |
SUCCESS | S | Registration succeeded. | |
PROCESS_FAIL | F | A general business failure occurred. Do not retry. | Human intervention is usually needed. It is recommended that you contact WorldFirst Technical Support to resolve the issue. |
UNKNOWN_EXCEPTION | U | The API call is failed, which is caused by unknown reasons. | The service might be down, retry later. If the issue persists, contact WorldFirst Technical Support. |
GMM_AUDITING_RECTIFY | F | Customer registration failed to pass the auditing. Rectify the information and retry. | |
EXPIRED_CERTIFICATE | F | The certificate is expired. | Retry with the correct certification information. |
CUSTOMER_ALREADY_EXIST | F | The customer's phone number is already registered or used. | Retry with the correct Customer information. |
BIZ_LICENSE_CANCELED | F | The submitted business license is canceled. | Retry with the correct business license information. |
BIZ_LICENSE_REVOKED | F | The submitted business license is revoked. | Retry with the correct business license information. |
BIZ_LICENSE_LEGAL_INFO_NO_MATCH | F | The submitted business license does not match the provided legal information. Retry with the correct information. | Retry with the correct business license information. |
USER_FORBIDEN | F | The user is forbidden. | Make sure the user information is correct and try again. |
USER_KYC_NOT_QUALIFIED | F | Registration failed due to the user's KYC status. The user is either not KYC compliant, or the KYC status is not qualified. | Complete the KYC verification first. |
KYC_FAILED | F | The Customer failed to pass KYC. | Complete the KYC verification first. |
REGISTER_BY_OTHER_CUSTOMER | F | The Customer has already registered with WorldFirst(Alipay). | Make sure the user information is correct and try again. |
RISK_AUDITING_REJECT | F | The registration request is rejected after risk auditing. | The Partner needs to complete the risk assessment upon the Customer. |
SUBMIT_FAIL | F | The submission failed. | |
ATTACHMENT_NOT_MATCH | F | The submitted attachment does not match the information on the certificate. Retry with the correct information. | Retry with the correct attachment information. |
result.ResultCode
resultCode | resultStatus | resultMessage | Further action |
SUCCESS | S | Success | |
PROCESS_FAIL | F | A general business failure occurred. Do not retry. | Human intervention is usually needed. It is recommended that you contact WorldFirst Technical Support to resolve the issue. |
PARAM_ILLEGAL | F | Illegal parameters exist. For example, a non-numeric input, or an invalid date. | Check and verify whether the request fields, including the header fields and body fields, are correct and valid. For details on the fields of each API, see the specific API Structure section. |
INVALID_SIGNATURE | F | The signature is invalid. | Make sure the request is properly signed with a valid signature. For more details, refer to the following chapter:
|
REPEAT_REQ_INCONSISTENT | F | Repeated requests are inconsistent. | Ensure all the fields in the requests are the same and try again. |
UNKNOWN_EXCEPTION | U | The API call is failed, which is caused by unknown reasons. | The service might be down, retry later. If the issue persists, contact WorldFirst Technical Support. |
SYSTEM_ERROR | F | Alipay system error | Do not retry, and contact Alipay Technical Support for more details. |
REQUEST_TRAFFIC_EXCEED_LIMIT | U | The request traffic exceeds the limit. | Call the interface again to resolve the issue. If the issue persists, contact WorldFirst Technical Support. |
Samples
Case 1. Company registration
Request
The following example assumes that the Partner registers a company as the beneficiary on WorldFirst(Alipay).
{
"registerRequestId": "******",
"customer": {
"referenceCustomerId": "******",
"customerType": "BUSINESS_PARTNER",
"businessPartner": {
"businessContactEntities": [
{
"businessContactType": "UBO",
"individual": {
"wealthSources": ["***","***"],
"contactAddress": {
"address1": "**区北**路**号",
"city": "110000",
"region": "CN",
"state": "11"
},
"attachments": [
{
"attachmentName": "Front side of ID Card",
"attachmentType": "ID_CARD_FRONT_SIDE",
"file": "qwertyuiop"
},
{
"attachmentName": "Back side of ID Card",
"attachmentType": "ID_CARD_BACK_SIDE",
"file": "qwertyuiop"
}
],
"birthDate": "1900-12-12T00:00:00+08:00",
"certificates": [
{
"certificateNo": "qwertyuiop",
"certificateType": "ID_CARD",
"effectivePeriodType": "TIME_RANGE",
"expireDate": "9999-12-31T00:00:00+08:00",
"holderName": {
"fullName": "***"
}
}
],
"legalName": "***",
"gender": "FEMALE",
"nationality": "CN"
},
"legalEntityType": "INDIVIDUAL",
"shareHoldingRatio": "1"
},
{
"businessContactType": "BOARD_MEMBER",
"individual": {
"attachments": [
{
"attachmentName": "Passport personal information page",
"attachmentType": "PASSPORT_PERSONAL_INFORMATION_PAGE",
"file": "qwertyuiop"
}
],
"certificates": [
{
"certificateNo": "qwertyuiop",
"certificateType": "PASSPORT",
"effectivePeriodType": "LONG_TERM",
"holderName": {
"fullName": "***"
}
}
],
"legalName": "***"
},
"legalEntityType": "INDIVIDUAL"
},
{
"businessContactType": "LEGAL_REPRESENTATIVE",
"individual": {
"attachments": [
{
"attachmentName": "Front side of ID Card",
"attachmentType": "ID_CARD_FRONT_SIDE",
"file": "qwertyuiop"
},
{
"attachmentName": "Back side of ID Card",
"attachmentType": "ID_CARD_BACK_SIDE",
"file": "qwertyuiop"
}
],
"certificates": [
{
"certificateNo": "qwertyuiop",
"certificateType": "ID_CARD",
"effectivePeriodType": "LONG_TERM",
"holderName": {
"fullName": "***"
}
}
],
"legalName": "***"
},
"legalEntityType": "INDIVIDUAL"
}
],
"businessName": "*** CO.,LIMITED",
"websites": [
{
"url": "https://taobao.com"
}
],
"mcc": "5399"
},
"legalEntityType": "COMPANY",
"company": {
"companyType": "COMPANY",
"industryType":"xxxxxxxxx",
"businessName": "",
"businessAddress": {
"address1" : "**区**路**号",
"city" : "110000",
"region" : "CN",
"state" : "11"
},
"legalName": "Company Name ABC",
"enterpriseType": "IPO",
"stockCode": "***",
"stockMarket": "HK",
"registrationAddress": {
"region": "CN",
"address1": "杭州市西湖区*路*号*层***室"
},
"attachments": [
{
"attachmentType": "BUSINESS_LICENSE",
"file": "/certifyPicture/TB1qc6BXp1LDuNjme7sXXbmYpXa?xsig=b1f540973da96aasdfsdfasdfas",
"attachmentName": "this is the business license URL"
}
],
"contactWays": [
{
"contactWayInfo": "1871111****",
"contactWayType": "PHONE",
"contactWayDesc": "mobile phone"
},
{
"contactWayInfo": "021-45****",
"contactWayType": "CS_PHONE",
"contactWayDesc": "mobile phone"
}
],
"certificates": [
{
"certificateType": "BUSINESS_LICENSE",
"certificateNo": "911111111111111****",
"effectivePeriodType": "LONG_TERM",
"effectiveDate" : "2012-08-10T00:00:00+08:00",
"holderName": {
"fullName": "legal person name"
}
}
],
"extendInfo": "\"OPERATION_ADDRESS\":\"***\""
}
},
"products": [
{
"productType": "ALIPAY_BUSINESS"
},
{
"productType": "ALIPAY_CN"
}
],
"accounts": [
{
"multipleCurrencies": [
"CNY",
"USD"
]
}
]
}
Response
{
"result": {
"resultCode": "SUCCESS",
"resultStatus": "S",
"resultMessage": "success"
},
"registerDetail": {
"registerStatus": "PROCESSING"
},
"referenceCustomerId": "******",
"customerId": "******",
"registerRequestId": "******"
}
Case 2. Individual registration
The following examples assume that Partner registers an individual as the beneficiary on WorldFirst(Alipay).
Request
{
"registerRequestId": "2021******",
"customer": {
"referenceCustomerId": "******",
"customerType": "BUSINESS_PARTNER",
"businessPartner": {
"mcc": "5399",
"websites": [{
"url": "abc.com"
}]
},
"legalEntityType": "INDIVIDUAL",
"individual": {
"legalName": "**",
"gender": "MALE",
"birthDate": "1992-05-21T00:00:00+08:00",
"nationality": "CN",
"contactAddress": {
"region": "CN",
"state": "***",
"city": "***",
"address1": "***"
},
"contactWays": [{
"contactWayType": "PHONE",
"contactWayInfo": "86-185******",
"contactWayDesc": "mobile phone"
}, {
"contactWayType": "EMAIL",
"contactWayInfo": "***@qq.com",
"contactWayDesc": "email address"
}],
"certificates": [{
"certificateType": "ID_CARD",
"certificateNo": "****************",
"effectivePeriodType": "TIME_RANGE",
"effectiveDate": "2018-09-03T00:00:00+08:00",
"expireDate": "*************:00:00+08:00",
"holderName": {
"fullName": "**"
}
}],
"attachments": [{
"attachmentType": "ID_CARD_FRONT_SIDE",
"file": "qwertyuiop1234567890",
"attachmentName": "Front side of ID Card"
}, {
"attachmentType": "ID_CARD_BACK_SIDE",
"file": "qwertyuiop1234567890",
"attachmentName": "Back side of ID Card"
}]
}
},
"products": [{
"productType": "ALIPAY_BUSINESS"
}, {
"productType": "ALIPAY_CN"
}],
"accounts": [{
"multipleCurrencies": ["CNY"]
}]
}
Response
{
"customerId": "******",
"referenceCustomerId": "******",
"registerDetail": {
"registerStatus": "PROCESSING"
},
"registerRequestId": "******",
"result": {
"resultCode": "SUCCESS",
"resultMessage": "success",
"resultStatus": "S"
}
}
References
Valid values for industryType
Number | Industry Type |
1. | Crop and animal production, hunting and related service activities |
2. | Forestry and logging |
3. | Fishing and aquaculture |
4. | Mining of coal and lignite |
5. | Extraction of crude petroleum and natural gas |
6. | Mining of metal ores |
7. | Other mining and quarrying |
8. | Mining support service activities |
9. | Manufacture of food products |
10. | Manufacture of beverages |
11. | Manufacture of tobacco products |
12. | Manufacture of textiles |
13. | Manufacture of wearing apparel |
14. | Manufacture of articles of fur |
15. | Manufacture of leather and related products |
16. | Manufacture of wood and of products of wood and cork, except furniture; manufacture of articles of straw and plaiting materials |
17. | Manufacture of paper and paper products |
18. | Printing and reproduction of recorded media |
19. | Manufacture of coke and refined petroleum products |
20. | Manufacture of chemicals and chemical products |
21. | Manufacture of basic pharmaceutical products and pharmaceutical preparations |
22. | Manufacture of rubber and plastic products |
23. | Manufacture of rubber products |
24. | Manufacture of other non-metallic mineral products |
25. | Manufacture of basic metals |
26. | Manufacture of basic precious and other non-ferrous metals |
27. | Manufacture of fabricated metal products, except machinery and equipment |
28. | Manufacture of weapons and ammunition |
29. | Manufacture of computer, electronic and optical products |
30. | Manufacture of electrical equipment |
31. | Manufacture of machinery and equipment n.e.c. |
32. | Manufacture of motor vehicles, trailers and semi-trailers |
33. | Manufacture of other transport equipment |
34. | Building of ships and boats |
35. | Manufacture of furniture |
36. | Other manufacturing |
37. | Manufacture of jewellery, bijouterie and related articles |
38. | Repair and installation of machinery and equipment |
39. | Electricity, gas, steam and air conditioning supply |
40. | Water collection, treatment and supply |
41. | Sewerage |
42. | Waste collection, treatment and disposal activities; materials recovery |
43. | Remediation activities and other waste management services |
44. | Construction of buildings |
45. | Civil engineering |
46. | Specialised construction activities |
47. | Wholesale and retail trade and repair of motor vehicles and motorcycles |
48. | Sale of motor vehicles |
49. | Wholesale trade, except of motor vehicles and motorcycles |
50. | Wholesale on a fee or contract basis |
51. | Agents involved in the sale of machinery, industrial equipment, ships and aircraft |
52. | Wholesale of agricultural raw materials and live animals |
53. | Wholesale of food and beverages |
54. | Wholesale of alcoholic and other beverages |
55. | Wholesale of tobacco products |
56. | Wholesale of household goods |
57. | Wholesale of watches and jewellery |
58. | Wholesale of information and communication equipment |
59. | Wholesale of other machinery, equipment and supplies |
60. | Other specialised wholesale |
61. | Wholesale of solid, liquid and gaseous fuels and related products |
62. | Wholesale of metals and metal ores |
63. | Non-specialised wholesale trade |
64. | Retail trade, except of motor vehicles and motorcycles |
65. | Retail sale in non-specialised stores |
66. | Retail sale of food, beverages in specialised stores |
67. | Retail sale of tobacco products in specialised stores |
68. | Retail sale of automotive fuel in specialised stores |
69. | Retail sale of information and communication equipment in specialised stores |
70. | Retail sale of other household equipment in specialised stores |
71. | Retail sale of cultural and recreation goods in specialised stores |
72. | Retail sale of other goods in specialised stores |
73. | Dispensing chemist in specialised stores |
74. | Retail sale of antiques including antique books, in stores |
75. | Retail sale in commercial art galleries |
76. | Retail sale via stalls and markets |
77. | Retail trade not in stores, stalls or markets (E-Commerce) |
78. | Online Sales via Live Streaming Platform |
79. | Land transport and transport via pipelines |
80. | Water transport |
81. | Air transport |
82. | Warehousing and support activities for transportation |
83. | Postal and courier activities |
84. | Accommodation |
85. | Food and beverage service activities |
86. | Publishing activities |
87. | Software publishing |
88. | Motion picture, video and television programme production, sound recording and music publishing activities |
89. | Programming and broadcasting activities |
90. | Telecommunications |
91. | Computer programming, consultancy and related activities |
92. | Information service activities |
93. | Financial service activities, except insurance and pension funding |
94. | Insurance, reinsurance and pension funding, except compulsory social security |
95. | Activities auxiliary to financial services and insurance activities |
96. | Virtual Currency Trading, Exchange or Supply (Crypto, Gaming Currency, etc) |
97. | Real estate activities |
98. | Legal and accounting activities |
99. | Management consultancy activities |
100. | Architectural and engineering activities; technical testing and analysis |
101. | Scientific research and development |
102. | Advertising and market research |
103. | Other professional, scientific and technical activities |
104. | Veterinary activities |
105. | Rental and leasing activities |
106. | Employment activities |
107. | Travel agency, tour operator and other reservation service and related activities |
108. | Security and investigation activities |
109. | Services to buildings and landscape activities |
110. | Office administrative, office support and other business support activities |
111. | Public administration and defence; compulsory social security |
112. | Education |
113. | Human health activities |
114. | Residential care activities |
115. | Social work activities without accommodation |
116. | Charities/NGOs/Non-Profit Organisations |
117. | Creative, arts and entertainment activities |
118. | Libraries, archives, museums and other cultural activities |
119. | Gambling and betting activities |
120. | Sports activities and amusement and recreation activities |
121. | Live Streaming Entertainment |
122. | Adult Entertainment / Pornographic Materials |
123. | Activities of membership organisations |
124. | Activities of religious organisations |
125. | Activities of other membership organisations |
126. | Repair of computers and personal and household goods |
127. | Other personal service activities |
128. | Activities of households as employers of domestic personnel |
129. | Undifferentiated goods- and services-producing activities of private households for own use |
130. | Activities of extraterritorial organisations and bodies |