tencent cloud

All product documents
Integration Process
Last updated: 2025-01-15 15:47:05
Integration Process
Last updated: 2025-01-15 15:47:05
This document introduces the overall integration process of eKYC selfie verification (mobile HTML5).

Preparations

Sign up for a Tencent Cloud account. For more information, see Signing Up.
Complete enterprise identity verification. For more information, see Enterprise Identity Verification Guide.
Log in to the eKYC console.

Overall Architecture

The following figure shows the architecture of eKYC selfie verification (mobile HTML5).




Overall Interaction Flow

The following diagram shows the overall interaction logic between customers and Tencent Cloud eKYC. Role descriptions are as follows:
User: H5 users on mobile
Merchant WebPage: customer’s frontend page
Merchant Server: customer’s backend server
eKYC WebPage: the eKYC frontend page
eKYC Server: the eKYC backend server



The specific recommended interaction flow is as follows:

Phase 1

1. The client service triggers a verification process.
2. Merchant WebPage sends a request to Merchant Server for initiating a verification process.
3. Merchant Server passes in relevant parameters and calls the ApplyWebVerificationBizTokenIntl. Refer to Step 1 of Server Integration.
4. After receiving the request, eKYC Server returns BizToken and VerificationURL of this verification process to Merchant Server.
5. Merchant Server keeps the BizToken and sends VerificationURL to Merchant WebPage.

Phase 2

1. Merchant WebPage redirects to VerificationURL to open eKYC WebPage. Refer to Step 1 of Frontend Integration.
2. The user performs the license OCR and verification process on eKYC WebPage.
3. After verification completed, eKYC Server sends the result to eKYC WebPage, and Merchant WebPage displays the result.
4. After the user clicks Next, eKYC WebPage will redirect to RedirectURL and splice the token parameter on the URL.
5. Merchant WebPage obtains token parameter of the current verification process through the address. Refer to Step 2 of Frontend Integration.

Phase 3

1. Merchant WebPage sends a request to Merchant Server for obtaining verification result information.
2. Merchant Server passes in relevant parameters and calls the GetWebVerificationResultIntl. Refer to Step 2 of Server Integration.
3. After receiving the request, eKYC Server returns details of this verification process to Merchant Server.
4. Merchant Server returns the result to Merchant WebPage which will perform subsequent business processes according to the result.

Server Integration

1. Call the interface ApplyWebVerificationBizTokenIntl to generate verification URL (corresponding to Stage 1)

Call ApplyWebVerificationBizTokenIntl to obtain BizToken and VerificationURL, corresponding to No.3 of the flow diagram.
‌RedirectURL: the Web address redirected after verification, including protocol header, hostname, and path, e.g., https://www.tencentcloud.com/products/faceid. After the verification process completed, the redirect address will be spliced to BizToken of the current process in the format as follows: https://www.tencentcloud.com/products/faceid? token={BizToken}.
Extra: the service pass-through parameter, up to 1000 characters. It will be returned in the GetWebVerificationResultIntl interface. It can be omitted if it is not necessary.
Config: the relevant configuration of custom verification page.
AutoSkip: whether to skip the result page and automatically jump to RedirectURL when verification succeeds. The default is false.
CheckMode: the detection mode. This parameter is required. Parameter values are as follows: 1: OCR+ liveness detection + face comparison.
IDCardType: the license type that supports identification. This parameter is required. The license supported currently are as follows:
HKIDCard: Hong Kong (China) ID Card
MLIDCard: Malaysian ID Card
IndonesiaIDCard: Indonesian ID Card
PhilippinesVoteID: Philippine Voter Card
PhilippinesDrivingLicense: Philippines Driving License
PhilippinesTinID: Philippines TinID
Philippines SSSID: Philippines SSSID
PhilippinesUMID: Philippines UMID
InternationalID Passport: Passport of Hong Kong, Macao, Taiwan (China), and other countries
IndonesiaDrivingLicense: Indonesian Driving License
ThailandIDCard: Thailand ID Card
ThailandDrivingLicense: Thailand Driving License
MLDrivingLicense: Malaysia Driving License
SingaporeIDCard: Singapore ID Card
SingaporeDrivingLicense: Singapore Driving License
Japanese ID Card: Japanese ID Card
Japanese Driving License
PhilippinesIDCard: Universal Philippine ID Card
DisableCheckOcrWarnings: whether to disable license alarms. The default is false (alarm detection is enabled). When enabled, the identity authentication process will be intercepted according to the license alarm. If you need to use license authentication function, please Contact Us.

Code example of calling interfaces:

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. The secretId and secretKey of Tencent Cloud account shall be passed in. Note: keep the key pair confidential here.
// Obtain the key at https://console.cloud.tencent.com/cam/capi
Credential cred = new Credential(
"TENCENTCLOUD_SECRET_ID",
"TENCENTCLOUD_SECRET_KEY"
);
// Instantiate an http option, optional. Skip this if there are no special requirements.
HttpProfile httpProfile = new HttpProfile();
httpProfile.setEndpoint("faceid.tencentcloudapi.com");
// Instantiate a client option, optional. Skip this if there are no special requirements.
ClientProfile clientProfile = new ClientProfile();
clientProfile.setHttpProfile(httpProfile);
// Instantiate the client object of the product to be requested. The clientProfile is optional.
FaceidClient client = new FaceidClient(cred, "ap-singapore", clientProfile);
// Instantiate a request object, one for each interface.
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 “resp” returned is an instance of ApplyWebVerificationBizTokenIntlResponse, corresponding to the request object.
ApplyWebVerificationBizTokenIntlResponse resp = client.ApplyWebVerificationBizTokenIntl(req);
// The string response package output 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());
}
}
}

2. Confirm results of the current verification process (corresponding to Stage 3)

After the verification completed, Merchant Frontend notifies Merchant Server to obtain the result of this verification. Merchant Server calls the GetWebVerificationResultIntl to return the result to frontend page, corresponding to No.12 of the flow diagram.
The license OCR result of this verification can be obtained from the responsive “OCRResult” field. The license OCR process can be regarded as success if the “OCRResult” field is not null, and the information of the corresponding certificate can be obtained. In other cases, it can be regarded as failure. For more information about the “OCRResult” field, refer to OCRResult documentation.
The result of this verification shall be based on the information returned by this interface. When the responsive “ErrorCode” field is 0, this verification process is deemed to have passed. In other cases, it is deemed to have failed. For error code list, refer to Liveness Detection and Face Comparison (Mobile HTML5) Error Codes.
BizToken: the BizToken generated by the ApplyWebVerificationBizTokenIntl, a unique identifier of the current verification process.

Code example of calling interfaces:

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. The secretId and secretKey of Tencent Cloud account shall be passed in. Note: keep the key pair confidential here.
// Obtain the key at https://console.cloud.tencent.com/cam/capi
Credential cred = new Credential(
"TENCENTCLOUD_SECRET_ID",
"TENCENTCLOUD_SECRET_KEY"
);
// Instantiate an http option, optional. Skip this if there are no special requirements.
HttpProfile httpProfile = new HttpProfile();
httpProfile.setEndpoint("faceid.tencentcloudapi.com");
// Instantiate a client option, optional. Skip this if there are no special requirements.
ClientProfile clientProfile = new ClientProfile();
clientProfile.setHttpProfile(httpProfile);
// Instantiate the client object of the product to be requested. The clientProfile is optional.
FaceidClient client = new FaceidClient(cred, "ap-singapore", clientProfile);
// Instantiate a request object, one for each interface.
GetWebVerificationResultIntlRequest req = new GetWebVerificationResultIntlRequest();
req.setBizToken("xxx"); // Enter the BizToken returned from ApplyWebVerificationBizTokenIntl phase.
// The “resp” returned is an instance of GetWebVerificationResultIntlResponse, corresponding to the requested object.
GetWebVerificationResultIntlResponse resp = client.GetWebVerificationResultIntl(req);
// The string response package output in json format.
System.out.println(GetWebVerificationResultIntlResponse.toJsonString(resp));
Long errorCode = resp.getErrorCode();
String errorMsg = resp.getErrorMsg();
// For details of the “OCRResult” field, please refer to OCRResult related documents at https://www.tencentcloud.com/document/api/1061/49423#ocr result.
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

1. Obtain VerificationURL and redirect to initiate the verification process (corresponding to Stage 2)

The client frontend page obtains the VerificationURL requested by the server and redirects to enter the verification process. The user completes liveness comparison process according to the prompt, corresponding to No.6 of the flow diagram.

Code example:

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

2. Obtain BizToken from callback address, and request verification result from backend (corresponding to Stage 2)

After verification, the page will jump to RedirectURL which will splice BizToken parameters of the current process. The BizToken parameters can be obtained by parsing RedirectURL to pull the result information of this liveness comparison, corresponding to No.12 of the flow diagram.

Code example:

// Obtain RedirectURL
const RedirectURL = "https://*****? token={BizToken}";
// Parse to obtain BizToken parameter of RedirectURL, which is used to pull result information of this liveness comparison.
const bizToken = getURLParameter(RedirectURL, "token");
if (bizToken) {
// Use bizToken to pull result information of this liveness comparison.
}
/**
/ * Parse url parameters
/* @params url To query url
/* @params variable To query parameters
*/
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);
}

Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No

Feedback

Contact Us

Contact our sales team or business advisors to help your business.

Technical Support

Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.

7x24 Phone Support