tencent cloud

Integration Process

Unduh
Mode fokus
Ukuran font
Terakhir diperbarui: 2026-05-25 18:32:26
This document describes the overall integration process for eKYC liveness verification (Mobile H5).

Integration Preparation

To register a Tencent Cloud enterprise account, see Registration Guide.
Complete enterprise identity verification. For details, see Enterprise Identity Verification Guide.
Log in to the eKYC console to activate the service.

Overall Architecture Diagram

The following figure shows the architecture diagram for eKYC liveness verification (Mobile H5):

ekyc H5 architecture diagram (1).png#573px #437px



Overall Interaction Flow

The following figure illustrates the overall interaction logic between the customer and Tencent Cloud eKYC. The roles in the figure are described as follows:
User: Mobile H5 user
Merchant WebPage: Customer frontend page
Merchant Server: Customer backend service
eKYC WebPage: eKYC frontend page
eKYC Server: eKYC backend service



The detailed recommended interaction flow is as follows:

Stage 1: Applying for a Verification Token

Note:
After submission, the RuleId will be reviewed and activated within one business day.
1. The verification process is triggered by client-side business activities.
2. Merchant WebPage sends a request to Merchant Server, notifying it to initiate a verification process.
3. Merchant Server calls the ApplyWebVerificationBizTokenIntl API by passing in the relevant parameters. Refer to Step 1 of the server-side integration.
4. After receiving the request, eKYC Server returns the BizToken and VerificationURL for that verification process to Merchant Server.
5. Merchant Server saves the obtained BizToken and sends the VerificationURL to Merchant WebPage.

Stage 2: User Verification Execution

1. From Merchant WebPage, navigate to the VerificationURL to open the eKYC WebPage. Refer to Step 1 of the frontend integration.
2. The user completes the OCR document recognition and verification process on the eKYC WebPage.
3. After the verification is completed, eKYC Server sends the verification result to eKYC WebPage, and Merchant WebPage displays the result page.
4. After the user clicks Next, the eKYC WebPage is redirected to the RedirectURL, with the Token parameter appended to the URL.
5. The token parameter for the current verification process is obtained by Merchant WebPage from the URL. Refer to Step 2 of the frontend integration.

Stage 3: Obtaining Verification Results

1. Merchant WebPage sends a request to Merchant Server, notifying it to obtain the verification result information.
2. Merchant Server calls the GetWebVerificationResultIntl API by passing in the relevant parameters. Refer to Step 2 of the server-side integration.
3. After receiving the request, eKYC Server returns the detailed information of that verification process to Merchant Server.
4. Merchant Server returns the result information to Merchant WebPage, which then proceeds with the subsequent business process based on the result.



RuleId Configuration (Optional)

RuleId is a business process ID preconfigured in the Tencent Cloud eKYC console to simplify parameter passing during API calls.
Is it mandatory to create a RuleId?
It is not mandatory. You can choose one of the following two methods:
Method
Description
Advantages
Disadvantage
Scenarios
Method A: Using Config Parameters
Pass all configurations via the Config parameter when the API is called.
Flexible, no pre-configuration required
Full parameters must be passed in for each call.
Configurations change frequently, or dynamic control of the process is required.
Method B: Using RuleId
Pre-configure the process in the console, and pass only the RuleId when calling.
Simplifies invocation and centralizes management
Pre-configuration required, and approval takes one business day.
Fixed configurations, with multiple applications sharing the same process.
Parameter Priority
When both RuleId and Config are used, the priority rule is: Config configuration > RuleId configuration > default configuration.
Example:
If the RuleId is configured with IDCardType=HKIDCard
However, IDCardType=MLIDCard is passed in the Config.
The configuration that ultimately takes effect is MLIDCard from the Config.

Creating a RuleId (Optional)

The RuleId is used to invoke the configured business process. The creation steps are as follows:
1. Log in to the Tencent Cloud eKYC console. On the self-service access page, click Create Business Process.

2. Select the required product service, and then click Next.

3. Go to the Privacy Agreement Configuration page. Based on your business needs, select whether to skip the privacy agreement page and choose a theme color, then click Next.

4. Go to the OCR Configuration page, select the card and document types to be recognized for your business and the fields to be displayed on the recognition result page, and then click Next.

5. Go to the Liveness Detection Configuration page, select the liveness detection mode to be applied, confirm whether to skip the liveness startup page, and then click Next.

6. Configure whether to skip the result page and select a language. You can choose a system-built-in language or upload a custom language package based on the attached template, and then click Next.

7. Confirm that your configuration information is correct, and then click Confirm. After submission, the RuleId will be reviewed and activated within one business day.


Server-Side Integration

Calling the API to Apply for a Web Verification Token and Generate a Verification URL (Corresponding to Stage 1)

Call the ApplyWebVerificationBizTokenIntl API to obtain the BizToken and the verification address VerificationURL. This corresponds to point 3 in the sequence diagram.
RedirectURL: The Web callback address to redirect to after verification. It includes the protocol header, hostname, and path, for example: https://www.tencentcloud.com/products/faceid. After the verification process is completed, the BizToken for that session is appended to the callback address, and the redirection is performed in the format https://www.tencentcloud.com/products/faceid?token={BizToken}.
Extra: A business passthrough parameter. Its maximum length is 1000 characters, and it is returned in the GetWebVerificationResultIntl API. It can be omitted if not required.
RuleId: The business process ID generated by the Tencent Cloud eKYC console configuration. Using the RuleId can simplify Config parameter passing. The priority relationship is "Config configuration > RuleId configuration > default configuration".
Config: The configuration for customizing the verification page.
AutoSkip: Whether to skip the result display page and automatically redirect to the RedirectURL upon successful verification. The default value is false.
CheckMode: The detection mode. This parameter is required. The parameter values are as follows: 1: OCR + Liveness Detection + Face Comparison (Here, 1 indicates the Card and Document Liveness Face Comparison check mode).
IDCardType: The types of cards and documents that can be recognized. This parameter is required. The currently supported cards and documents are listed below:
HKIDCard: Hong Kong (China) ID Card
MLIDCard: Malaysian ID Card
IndonesiaIDCard: Indonesian ID Card
PhilippinesVoteID: Philippine Voter's ID Card
PhilippinesDrivingLicense: Philippine Driver's License
PhilippinesTinID: Philippine TinID
PhilippinesSSSID: Philippine SSSID
PhilippinesUMID: Philippine UMID
InternationalIDPassport: Passports from Hong Kong/Macao/Taiwan (China) and other countries/regions
ThailandIDCard: Thai ID Card
SingaporeIDCard: Singapore ID Card
MainlandIDCard: Mainland China ID Card
DisableCheckOcrWarnings: Whether to disable document alarms. The default value is false (the alarm detection feature is enabled). When it is enabled, the identity verification process will block operations based on the alarm status of the document. If you need to use the document authenticity verification feature, please contact us.

API Call Code Sample

import com.tencentcloudapi.common.Credential;
import com.tencentcloudapi.common.profile.ClientProfile;
import com.tencentcloudapi.common.profile.HttpProfile;
import com.tencentcloudapi.common.exception.TencentCloudSDKException;
import com.tencentcloudapi.faceid.v20180301.FaceidClient;
import com.tencentcloudapi.faceid.v20180301.models.*;

public class ApplyWebVerificationBizTokenIntl {
public static void main(String[] args) {
try {
// Instantiate an authentication object. Input parameters need to include secretId and secretKey of the Tencent Cloud account. Keep the confidentiality of the key pair.
// The key can be obtained at https://console.tencentcloud.com/cam/capi.
Credential cred = new Credential(
"TENCENTCLOUD_SECRET_ID",
"TENCENTCLOUD_SECRET_KEY"
);

// Instantiate an HTTP option (optional). Skip it if there are no special requirements.
HttpProfile httpProfile = new HttpProfile();
httpProfile.setEndpoint("faceid.intl.tencentcloudapi.com");

// Instantiate a client option (optional). Skip it if there are no special requirements.
ClientProfile clientProfile = new ClientProfile();
clientProfile.setHttpProfile(httpProfile);

// Instantiate the client object that requests the product. clientProfile is optional.
FaceidClient client = new FaceidClient(cred, "ap-singapore", clientProfile);

// Instantiate a request object. Each API will correspond to a request object.
ApplyWebVerificationBizTokenIntlRequest req = new ApplyWebVerificationBizTokenIntlRequest();
req.setRedirectURL("https://www.tencentcloud.com/products/faceid");

WebVerificationConfigIntl webVerificationConfigIntl = new WebVerificationConfigIntl();
webVerificationConfigIntl.setCheckMode(1L);
webVerificationConfigIntl.setIDCardType("HKIDCard");
req.setConfig(webVerificationConfigIntl);

// The returned `resp` is an instance of `ApplyWebVerificationBizTokenIntlResponse`, which corresponds to the request object.
ApplyWebVerificationBizTokenIntlResponse resp = client.ApplyWebVerificationBizTokenIntl(req);

// Output a string packet in JSON format.
System.out.println(ApplyWebVerificationBizTokenIntlResponse.toJsonString(resp));

String bizToken = resp.getBizToken();
String verificationURL = resp.getVerificationURL();
System.out.printf("BizToken: %s, VerificationURL: %s", bizToken, verificationURL);
} catch (TencentCloudSDKException e) {
System.out.println(e.toString());
}
}
}



Confirming the Result of the Current Verification Process (Corresponding to Phase 3)

After the verification process is completed, the merchant frontend notifies the merchant server to obtain the verification result. The merchant server then calls the GetWebVerificationResultIntl API and returns the final result to the frontend page. This corresponds to point 12 in the sequence diagram.
The final verification result should be based on the information returned by this API. The verification process is considered passed when the ErrorCode field in the response is 0, and considered failed in all other cases. For a detailed list of error codes, see Liveness Detection and Face Comparison (Mobile HTML5) Error Codes.
BizToken: The BizToken generated by the ApplyWebVerificationBizTokenIntl API. It serves as the unique identifier for that verification session.

API Call Code Sample

import com.tencentcloudapi.common.Credential;
import com.tencentcloudapi.common.profile.ClientProfile;
import com.tencentcloudapi.common.profile.HttpProfile;
import com.tencentcloudapi.common.exception.TencentCloudSDKException;
import com.tencentcloudapi.faceid.v20180301.FaceidClient;
import com.tencentcloudapi.faceid.v20180301.models.*;

import java.util.Arrays;

public class GetWebVerificationResultIntl {
public static void main(String[] args) {
try {
// Instantiate an authentication object. Input parameters need to include secretId and secretKey of the Tencent Cloud account. Keep the confidentiality of the key pair.
// The key can be obtained at https://console.tencentcloud.com/cam/capi.
Credential cred = new Credential(
"TENCENTCLOUD_SECRET_ID",
"TENCENTCLOUD_SECRET_KEY"
);

// Instantiate an HTTP option (optional). Skip it if there are no special requirements.
HttpProfile httpProfile = new HttpProfile();
httpProfile.setEndpoint("faceid.intl.tencentcloudapi.com");

// Instantiate a client option (optional). Skip it if there are no special requirements.
ClientProfile clientProfile = new ClientProfile();
clientProfile.setHttpProfile(httpProfile);

// Instantiate the client object that requests the product. clientProfile is optional.
FaceidClient client = new FaceidClient(cred, "ap-singapore", clientProfile);

// Instantiate a request object. Each API will correspond to a request object.
GetWebVerificationResultIntlRequest req = new GetWebVerificationResultIntlRequest();
req.setBizToken("xxx"); // Enter the BizToken returned by the ApplyWebVerificationBizTokenIntl stage.

// The returned `resp` is an instance of `GetWebVerificationResultIntlResponse`, which corresponds to the request object.
GetWebVerificationResultIntlResponse resp = client.GetWebVerificationResultIntl(req);

// Output a string packet in JSON format.
System.out.println(GetWebVerificationResultIntlResponse.toJsonString(resp));

Long errorCode = resp.getErrorCode();
String errorMsg = resp.getErrorMsg();
// For details about the OCRResult fields, see the OCRResult documentation.
// https://www.tencentcloud.com/document/api/1061/49423#ocrresult
OCRResult[] ocrResult = resp.getOCRResult();

if (errorCode == 0) {
// Verification passed
System.out.println("Success");
System.out.printf("OCRResult:%s", Arrays.toString(ocrResult));
} else {
// Verification failed
System.out.printf("Fail: %s\\n", errorMsg);
}
} catch (TencentCloudSDKException e) {
System.out.println(e.toString());
}
}
}

Frontend Integration

Obtaining the VerificationURL and Redirecting to Initiate the Verification Process (Corresponding to Phase 2)

The customer frontend page obtains the VerificationURL requested by the server and redirects to that address to enter the verification process. The user then completes the liveness comparison process by following the prompts. This corresponds to point 6 in the sequence diagram.

Sample Code

// Obtain the VerificationURL from the server
const VerificationURL = 'https://sg.faceid.qq.com/reflect/?token=*****';
// Frontend page redirect
window.location.href = VerificationURL;

Obtaining the BizToken from the Callback URL and Requesting the Verification Result from the Backend (Corresponding to Phase 2)

After the verification is completed, the page is redirected to the RedirectURL. The BizToken parameter for that session is appended to the RedirectURL. You can obtain the BizToken parameter by parsing the RedirectURL and use it to retrieve the result information of this liveness comparison. This corresponds to point 12 in the sequence diagram.

Sample Code

// Obtain the RedirectURL
const RedirectURL = "https://*****?token={BizToken}";

// Parse the BizToken parameter from the RedirectURL to retrieve the result information of this liveness comparison.
const bizToken = getURLParameter(RedirectURL, "token");
if (bizToken) {
// Use the bizToken to retrieve the result information of this liveness comparison.
}

/**
// Parse the url parameters
* @param {string} url The query url
* @param {string} variable The query parameter
* @returns {string|false}
*/
function getURLParameter(url, variable) {
const query = url.split('?')[1] || '';
const vars = query.split('&');
for (let i = 0; i < vars.length; i++) {
const pair = vars[i].split('=');
if (pair[0] === variable) {
return pair[1];
}
}
return false;
}


Bantuan dan Dukungan

Apakah halaman ini membantu?

masukan