InitFaceVerify

Updated at:

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.

Important

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:

  1. Configure consumption alerts: Set high-value consumption alerts to monitor your spending in real time.

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

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

{
  "zimVer": "3.0.0",
  "appVersion": "1",
  "bioMetaInfo": "4.1.0:1150****,0",
  "appName": "com.aliyun.antcloudauth",
  "deviceType": "ios",
  "osVersion": "iOS 10.3.2",
  "apdidToken": "",
  "deviceModel": "iPhone9,1"
}
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:

  • 1: User input. The end user manually enters the document information through the UI provided by the Alibaba Cloud SDK.

  • 3: External parameters. The document information is passed in from an external source.

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 CertType is set to PASSPORT and Mode is set to 3.

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 CertType is set to PASSPORT and Mode is set to 3.

1993-10-10

ValidityDate

String

No

The expiration date of the document.

This parameter is required when CertType is set to PASSPORT and Mode is set to 3.

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 CallbackToken field.

NMjvQanQgplBSaEI0sL86WnQplB

callbackUrl

String

No

The callback URL for receiving verification result notifications. The URL must start with HTTPS.

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 verify() function to start the NFC verification.

Important
  • This ID is used for billing and statistics. We recommend storing it for billing reconciliation.

  • This ID is valid for 30 minutes and supports only a single verification attempt.

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 AliyunAntCloudAuthFullAccess policy to the RAM user.

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.