InitFaceVerify
This topic describes how to call the InitFaceVerify API to initiate a financial-grade NFC verification request.
Initiate a verification request
API operation: InitFaceVerify
Global endpoint: cloudauth.aliyuncs.com (IPv4) or cloudauth-dualstack.aliyuncs.com (IPv6)
Request method: POST and GET
Transport protocol: HTTPS
Description: Call this API before each verification to obtain a CertifyId, which links all API calls for a single authentication request.
QPS limit: Each API has a dedicated limit. See Server-side API QPS limits.
The Financial-grade Real Person Authentication service does not currently support hard caps or automatic suspension based on the number of calls. To control costs and prevent unexpected charges, configure consumption alert rules immediately after integration:
Configure consumption alerts: Set high-value consumption alerts to monitor your spending in real time.
Monitor your resource plan balance: If you have purchased a resource plan, set a resource plan balance alert so you can top up the plan or adjust your call strategy promptly.
Configure business monitoring: See Alert notification settings to monitor for business anomalies and request fluctuations.
Request parameters
Parameter | Type | Required | Description | Example |
SceneId | Long | Yes | The ID of the verification scenario. This ID is generated after you create a verification scenario in the console. To learn how to create one, see Add a verification scenario. | 100000**** |
OuterOrderNo | String | Yes | A custom, unique business ID for troubleshooting. The ID must be a unique alphanumeric string of up to 32 characters. | e0c34a77f5ac40a5aa5e6ed20c35**** |
ProductCode | String | Yes | The verification solution. The only valid value is NFC_QY. | NFC_QY |
UserId | String | Yes | A custom user ID. The ID must be unique and can contain up to 100 characters. | 12345**** |
CertType | String | Yes | The document type. Note Currently, only passport verification is supported. | PASSPORT |
ReadImg | String | Yes | Specifies whether to read the document photo. Valid values: Y: Read the photo. N: Do not read the photo. Note Set this parameter to Y if you need the document holder's photo for subsequent verification steps. | Y |
MetaInfo | String | Yes | Environment parameters obtained from the client SDK. For more information, see App (SDK) integration. | Note This example is for reference only. Do not use it directly in your integration. Obtain the actual value by following the SDK integration guide. |
Mode | String | No | The method for obtaining the required elements for passport NFC verification. Valid values:
Note NFC decoding of a passport chip requires three elements: the holder's name, date of birth, and the document's expiration date. | 1 |
CertNo | String | No | The document number. This parameter is required when | E123456**** |
CertName | String | No | The name on the document. | Zhang San |
Birthday | String | No | The date of birth on the document. This parameter is required when | 1993-10-10 |
ValidityDate | String | No | The expiration date of the document. This parameter is required when | 2039-06-10 |
Mobile | String | No | The mobile phone number of the end user. | 1304567**** |
Ip | String | No | The IP address of the end user. | 114.112.XX.XX |
CallbackToken | String | No | A security token you generate to prevent replay attacks and tampering. If you set this parameter, the callback notification includes the | NMjvQanQgplBSaEI0sL86WnQplB |
callbackUrl | String | No | The callback URL for receiving verification result notifications. The URL must start with | https://www.aliyun.com |
AuthId | String | No | The user authorization ID. The ID can be up to 64 characters long. | 92d46b9e9e2d703f2897f350d5bd4149 |
Response parameters
Parameter | Type | Required | Description | Example |
RequestId | String | Yes | The ID of the request. | 130A2C10-B9EE-4D84-88E3-5384FF03**** |
Message | String | No | The response message. | success |
Code | String | Yes | The status code. For more information about status codes, see Status codes and messages. | 200 |
ResultObject.CertifyId | String | No | The unique verification ID. The client passes this ID to the Important
| 91707dc296d469ad38e4c5efa6a0**** |
Status codes and messages
Code | Message | Description |
200 | success | The request was successful. |
400 | Parameter is empty | A required parameter is empty. |
401 | Invalid parameter | An invalid parameter was provided. Ensure that parameters such as name, document number, and date of birth comply with relevant standards. |
402 | Application configuration not found | The application configuration does not exist. |
404 | Verification scenario not found | The verification scenario configuration does not exist. Create a verification scenario in the console first. |
410 | Service not activated | The OSS service is not activated, or it lacks the necessary read/write permissions. Log on to the console to grant the required permissions. For more information, see Activate and authorize OSS. |
411 | RAM permission denied | The RAM user does not have the required permissions. Grant the |
412 | Overdue payment | Your account has an overdue payment for the financial-grade NFC verification service or OSS. Top up your account and try again. |
414 | Device does not support NFC | The current mobile device does not support NFC verification. Use a different device and try again. |
500 | System error | An internal system error occurred. Contact Alibaba Cloud technical support through Intelligent Online for assistance. |