inquiryRegisterCustomer

2022-05-13 12:00

POST: /aps/api/business/onboard/inquiryRegisterCustomer
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.

Once the Partner submits the request to register a Customer, the Partner can inquire about the result of the registration process with the inquiryRegisterCustomer interface. WorldFirst(Alipay) responds to the Partner with the result of the Customer registration process, together with other relevant information.

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

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

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 value of the individual.contactAddress field is the same as the address on the ID card.
customer.businessPartner.individual.wealthSources is required when a comapny has a UBO share holding over 25%.

Response parameters

Field	Data type	Required	Description
result	Result object	Yes	Indicates whether this API is called successfully.
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
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
registerRequestId	String	Yes	The unique ID assigned by the Partner to identify a registration request of a beneficiary. More information: Maximum length: 64 characters
registerDetail	RegisterDetail object	Yes	Details about registration such as the registration status.
requestedProducts	Array<Products object>	Yes	The product that the registered customer wants to use.
auditDetails	AuditDetail object	Yes(Conditional)	The detailed reasons for the submission failure. Note: This field is only required when the `registerDetail.reasonCode` is `GMM_AUDITING_RECTIFY`.

Result processing logic

After calling the API, a response is returned with two result codes, result.resultStatus and transferResult.resultStatus.

result.resultStatus indicates the result of the API request.
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.

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. The Partner can make another API call. Use the following query strategy: A Partner can make 7 queries at maximum. Intervals between queries: 5m, 10m, 20m, 40m, 80m, 160m, and 320m. If none of the queries is successful, 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: The signature field in a request header. How to calculate a signature.
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

The following example assumes that the partner queries the result of a registration of a beneficiary identified by the customerId of******.

Request

copy
{  
    "customerId":"******"
}

Response

When the registration succeeds:

copy
{
  "customerId": "******",
  "referenceCustomerId": "******",
  "registerDetail": {
    "registerStatus": "SUCCESS"
  },
  "registerRequestId": "********",
  "requestedProducts": [{
    "productStatus": "ACTIVE",
    "productType": "ALIPAY_CN"
  }],
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success",
    "resultStatus": "S"
  }
}

When the registration fails:

copy
{
    "customerId": "1234567890",
    "referenceCustomerId": "******",
    "registerDetail": {
        "reasonCode": "GMM_AUDITING_RECTIFY",
        "registerMessage": "register fail",
        "registerStatus": "FAILED"
    },
    "registerRequestId": "******",
    "requestedProducts": [
        {
            "productStatus": "INACTIVE",
            "productType": "ALIPAY_CN",
            "reasonCode": "GMM_AUDITING_RECTIFY"
        }
    ],
    "auditDetails": [
      {
       "auditKey":"customer.company.legalName",
       "auditReason":"imdp.reviewResult.notMatchActual",
       "auditKeyType":"Merchant",
       "certificateNo":"",
       "memo":"提供信息与实际信息不匹配"
      },
      {
       "auditKey":"businessPartner.businessContactEntities.boardMember.legalName",
       "auditReason":"imdp.reviewResult.notMatchActual",
       "auditKeyType":"Merchant",
       "certificateNo":"xxxxxxxx",
       "memo":"提供信息与实际信息不匹配"
      },
      {
       "auditKey":"businessPartner.businessContactEntities.ubo.legalName",
       "auditReason":"imdp.reviewResult.LackOfUBO",
       "auditKeyType":"Merchant",
       "certificateNo":"",
       "memo":"存在其他≥25%以上UBO信息"
      }
     ],
    "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "success",
        "resultStatus": "S"
    }
}

References

`auditDetails.auditReason`

`auditDetails.reviewReason`	Reason
imdp.reviewResult.notMatchActual	The submitted information does not match the actual information.
imdp.reviewResult.Repeat/LackofName	The submitted legal name/business name is lacking or repetitive.
imdp.reviewResult.TheCountryNoNeedRegister	The Customer does not need to register in the submitted country/region.
imdp.reviewResult.registrationFileIncorrect	The submitted registration file is incorrect.
imdp.reviewResult.fileVague	The submitted file is blurry and unreadable. Reupload with better quality.
imdp.reviewResult.fileFormatIncorrect	The format of the submitted file is incorrect.
imdp.reviewResult.Documenthasexpired	The documentation has expired.
imdp.reviewResult.fullColorID	The submitted file cannot be black-and-white. Reupload a colored scan of the ID.
imdp.documentIsAReproduction	The submitted documentation is a reproduction of the original copy. Reupload the original copy.
imdp.reviewResult.backofID	Reupload with the scan of the back side of ID.
imdp.reviewResult.selectSoleProprietorship	Mistaken company type. Retry and select the company as a sole proprietorship company.
imdp.reviewResult.selectCompany	Mistaken company type. Retry and select the company as a regular company.
imdp.reviewResult.selectPartnership	Mistaken company type. Retry and select the company as a partnership company.
imdp.reviewResult.other	Other reasons
imdp.reviewResult.noSPBRdoc3	The registration file does not match the Customer information.
imdp.reviewResult.IncorrectWatermark	The submitted file is unreadable due to watermarks.
imdp.reviewResult.NoCorrectDoc	The submitted file is not the original copy. Reupload the original copy.
imdp.reviewResult.provideNewBizLicence	Retry with the latest business license.
imdp.reviewResult.BRLackofSeal	The submitted business license is rejected due to lacking the official seal stamp.
imdp.reviewResult.IncompleteofFrameAndNationalEmblem	The submitted business license is rejected due to the frame being incomplete or the national emblem being incomplete.
imdp.reviewResult.LackofBR3	The submitted business license is rejected since it is not a "Three-in-One License".
imdp.reviewResult.NeedEnglishVersionDoc	Retry with the English version file or the official translated file.
imdp.reviewResult.prohibitedaccount	The industry that your company belongs to cannot be registered.
imdp.reviewResult.NoListedNoChoise	The company is not listed on the stock market.
imdp.reviewResult.NoListedNoFillin	The company does not need to fill in the related fields due to being a non-listed company.
imdp.reviewResult.LackOfDirector	Retry with the complete information about all the board members/legal representatives.
imdp.reviewResult.notCompanyLegalPerson	The submitted personnel is not one of the company's board members/legal representatives.
imdp.reviewResult.IDCopyIncorrect	The submitted ID is either incomplete or incorrect.
imdp.reviewResult.noMatchWatermark	The submitted file does not match or cause the file unreadable.
imdp.reviewResult.picturesofyourIDandupload	The submitted file is not the original copy. Reupload the photo of your original ID.
imdp.reviewResult.UBOPercentNoMatch	The UBO percentage in the submitted file is incorrect.
imdp.reviewResult.LackOfUBO	The submitted file does not disclose information about other UBO that holds more than 25% of the shares.
imdp.reviewResult.NotTheRealUBO	The submitted file contains unmatching UBO information.
imdp.reviewResult.NeedHK/TW/MOTrafficPremit	Reupload the file with the Mainland Travel Permit for Hong Kong/Macao/Taiwan Residents or passports.
imdp.reviewResult.LackofOverseaUBOdoc	The submitted file lacks UBO documentation for the oversea board members.

`auditDetails.auditKey`

When the business contact entity is an Individual:

auditDetails.auditReason	Specific key that was rejected during the review process
customer.individual.legalName	The full legal name of the individual.
customer.individual.birthDate	The birth date of the individual.
customer.individual.contactAddress	The contact address of the individual.
customer.individual.contactWays.contactWayInfo	The contact phone number of the individual.
customer.individual.nationality	The nationality of the individual.
customer.individual.certificates.certificateNo	The certificate number of the individual.
customer.individual.attachments	The photocopy attachment of the individual's ID card or passport.

When the business contact entity is a company:

auditDetails.auditReason	Specific key that was rejected during the review process	Type
customer.company.companyType	The type of the company.	Company
customer.company.legalName	The legal name of the company.
customer.company.certificates.certificateNo	The certificate number of the company.
customer.company.attachments	The attachments of the company's business registration documents.
customer.company.registrationAddress.region	The country/region where the company registers.
customer.company.registrationAddress	The registered address of the company.
customer.company.certificates.effectiveDate	The registered date of the company.
customer.company.industryType	The type of industry that the company belongs to.
customer.company.enterpriseType	The type of the enterprise, whether it is a listed company on the stock market.
customer.company.stockMarket	The country/region where the stock market of the listed company locates at.
businessPartner.businessContactEntities.legalRepresentative.certificates.certificateType	The type of the legal representative's certificate.	Legal representative
businessPartner.businessContactEntities.legalRepresentative.legalName	The legal name of the legal representative.
businessPartner.businessContactEntities.legalRepresentative.certificates.certificateNo	The certificate number of the legal representative.
businessPartner.businessContactEntitie.legalRepresentative.attachments	The attachment of the legal representative's certificate.
businessPartner.businessContactEntities.boardMember.certificates.certificateType	The type of the board member's certificate.	Board member
businessPartner.businessContactEntities.boardMember.legalName	The legal name of the board member.
businessPartner.businessContactEntities.boardMember.certificates.certificateNo	The certificate number of the board member.
businessPartner.businessContactEntitie.boardMember.attachments	The attachments of the board member's ID card.
businessPartner.businessContactEntities.ubo.certificates.certificateType	The type of the ultimate beneficial owner's certificate.	UBO
businessPartner.businessContactEntities.ubo.shareHoldingRatio	The ultimate beneficial owner's shareholding ratio (when it is above 25%0
businessPartner.businessContactEntities.ubo.legalName	The ultimate beneficial owner's name.
businessPartner.businessContactEntities.ubo.certificates.certificateNo	The ultimate beneficial owner's certificate number.
businessPartner.businessContactEntities.ubo.residentAddress.region	The country/region that the ultimate beneficial owner locates.
businessPartner.businessContactEntities.ubo.birthDate	The ultimate beneficial owner's birth date.
businessPartner.businessContactEntities.ubo.nationality	The ultimate beneficial owner's nationality.
businessPartner.businessContactEntities.ubo.attachments	The attachment of the ultimate beneficial owner's certificate.