DocsICP FilingConsole
官方文档
首页

InitCardVerify

更新时间：
复制 MD 格式
产品详情
我的收藏

This topic describes how to initiate a verification request by calling the InitCardVerify API.

API information

Important

Before you use this API, read the access process and activate the service.

API name: InitCardVerify

Global endpoint: cloudauth.aliyuncs.com (IPv4) or cloudauth-dualstack.aliyuncs.com (IPv6)

HTTP request method: POST and GET

Transport protocol: HTTPS

Description: Before starting each verification, call this API to obtain a CertifyId. This ID links all API calls for a single verification request.

QPS limit: This API has a dedicated QPS limit. For more information, see QPS limits for information verification APIs.

Important

The Information Verification Service does not support a hard cap on call volume or automatic deactivation. To control costs and prevent high bills, configure spending alert rules after you integrate the service:

  1. Configure spending alerts: Set a spending alert rule (Set high-spending alerts) to monitor your bills in real time.

  2. Monitor data transfer plan balance: If you purchased a data transfer plan, also monitor its balance (Configure remaining quota alerts) to add resources or adjust your call policy promptly.

Request parameters

Parameter

Type

Required

Description

Example

MerchantBizId

String

Yes

A custom, unique business identifier for tracking and troubleshooting issues.

The identifier can be up to 32 characters in length and can contain letters and digits. Make sure that the ID is unique.

e0c34a77f5ac40a5aa5e6ed2********

MetaInfo

String

Yes

The environment parameters obtained from the client SDK.

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

CardType

String

Yes

The document type. The value must be IDENTITY_CARD.

IDENTITY_CARD

Model

String

Yes

The verification method. Set the value to:

OCR_VERIFY: OCR recognition and verification.

OCR_VERIFY

VerifyMeta

String

Yes

The verification type. Set the value to:

ID_3_META: The three-element identity verification (name, ID number, and portrait photo).

ID_3_META

CardPageNumber

String

Yes

The number of document pages to capture with the SDK:

  • 1: Capture the front side.

  • 2: Capture both the front and back sides.

2

PictureSave

String

Yes

Specifies whether to temporarily store images captured by the app.

  • Y: Yes

  • N: No

Note

If you set this parameter to Y, the document images can be returned when you call the query API.

Y

CallbackUrl

String

No

The callback notification URL for authentication results only supports the HTTPS protocol.

After the certification is complete, the platform will call back this URL and automatically add the certifyId, passed, and subcode parameters. For example: https://www.aliyun.com?certifyId=xxxx&passed=T&subcode=200.

Warning

Callbacks are sent only for successful verifications. No notification is sent if a verification is abandoned, interrupted, or not performed. After receiving a callback, call the query API to retrieve detailed verification data.

https://www.aliyun.com

CallbackToken

String

No

The security token used for anti-replay and anti-tampering checks. If you specify this parameter, the CallbackToken field is included in the callback URL.

NMjvQanQgplBSaEI0sL86Wn****

DocScanMode

String

No

The capture mode. Valid values:

  • shoot: The user manually takes a photo.

  • scan: The user scans the document.

  • auto: The system automatically switches between the shoot and scan modes.

shoot

Response parameters

Parameter

Type

Description

Example

RequestId

String

The request ID.

130A2C10-B9EE-4D84-88E3-5384********

Message

String

The returned message.

success

Code

String

The response code. A value of 200 indicates a successful call. Other values indicate that the call failed.

Important

  • This parameter indicates whether the API call was successful. For detailed descriptions of the return codes, refer to server-side error codes.

  • To see the business verification result, check the fields in ResultObject.

200

ResultObject

CertifyId

String

The unique ID for the verification request.

Provide this ID when querying the verification result.

Warning

  • The CertifyId is used for billing and statistics. To simplify bill reconciliation, we recommend storing this ID locally.

  • The CertifyId from the initialization API is valid for 30 minutes and for a single verification attempt. Use it within the validity period and do not reuse it.

91707dc296d469ad38e4c5ef********

SDK examples

Important

Before you integrate, read the integration process, activate the service, and get an AccessKey and configure the environment variables.

Get SDK samples and installation packages:

  • On the online API debugging page in OpenAPI, find the SDK sample code on the right. Click SDK installation information in the upper-right corner of the code sample to view installation details.

    Note

    Select the required programming language.

    image

  • For offline installation, go to the SDK installation page, select the SDK for your programming language, and download it from the publishing address.

    image

Previous：Server-side integrationNext：DescribeCardVerify - Retrieve authentication results