registerCustomer

POST: /aps/api/business/onboard/registerCustomer

Signature required

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:

  • This field is an API idempotency field. For details about API idempotency, see the Idempotency chapter.

More information:

  • Maximum length: 64 characters

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.wealthSourcesfield 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:

  • Maximum length: 32 characters

referenceCustomerId

String

Yes

The unique ID assigned by the Partner to identify a Customer. In this case, a beneficiary.

More information:

  • Maximum length: 64 characters

registerRequestId

String

Yes

The unique ID assigned by the Partner to identify a Customer registration request.

More information:

  • Maximum length: 64 characters

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 is GMM_AUDITING_RECTIFY.
    • The detailed reason is elaborated by the auditDetails.auditReason field. For more details about auditReason, 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 result.resultCode.

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).

copy
{
    "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

copy
{
  "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

copy
{
  "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

copy
{
  "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

@2024 WorldFirst