tencent cloud

eKYC

DocumentationeKYCIntegration GuideSelfie Verification (Mobile HTML5)‌Integration Process

‌Integration Process

Download
Focus Mode
Font Size
Last updated: 2026-05-25 18:30:42
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

Step1.png#924px #715px


The detailed recommended interaction flow is as follows:

Stage 1: Applying for a Verification Token

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. Upon receiving the request, the eKYC Server returns the BizToken and VerificationURL for that verification process to the 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 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.

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.
CompareImageBase64: Compares the Base64-encoded string of a photo. The Base64-encoded string must not exceed 8 MB.
RedirectURL: The Web redirect address after verification is completed. 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 redirect 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.
Config: The configuration for customizing the verification page. It can be omitted if not required.
The Config data structure is as follows:
AutoSkip: Whether to skip the result display page and automatically redirect to the RedirectURL upon successful verification. The default value is false. For descriptions of other fields, see WebVerificationConfigIntl.

API Call Code Sample

package main

import (
	"fmt"
	"os"

	"github.com/tencentcloud/tencentcloud-sdk-go-intl-en/tencentcloud/common"
	"github.com/tencentcloud/tencentcloud-sdk-go-intl-en/tencentcloud/common/errors"
	"github.com/tencentcloud/tencentcloud-sdk-go-intl-en/tencentcloud/common/profile"
	"github.com/tencentcloud/tencentcloud-sdk-go-intl-en/tencentcloud/common/regions"
	faceid "github.com/tencentcloud/tencentcloud-sdk-go-intl-en/tencentcloud/faceid/v20180301"
)

func ApplyWebVerificationBizTokenIntl(imageBase64 string) {
	// Set the TencentCloud API access key
	credential := common.NewCredential(
		os.Getenv("TENCENTCLOUD_SECRET_ID"),
		os.Getenv("TENCENTCLOUD_SECRET_KEY"),
	)
	cpf := profile.NewClientProfile()
	client, _ := faceid.NewClient(credential, regions.Singapore, cpf)
	request := faceid.NewApplyWebVerificationBizTokenIntlRequest()
	request.RedirectURL = common.StringPtr("https://www.tencentcloud.com/products/faceid")
	// Pass in the CompareImageBase64 and Extra parameters
	request.CompareImageBase64 = common.StringPtr(imageBase64)
	request.Extra = common.StringPtr("ExtraString")
	response, err := client.ApplyWebVerificationBizTokenIntl(request)
	if _, ok := err.(*errors.TencentCloudSDKError); ok {
		fmt.Printf("An API error has returned: %s", err)
		return
	}
	if err != nil {
		panic(err)
	}
	// Obtain the BizToken and verificationURL
	bizToken := *response.Response.BizToken
	verificationURL := *response.Response.VerificationURL
	fmt.Printf("BizToken: %s, VerificationURL: %s", bizToken, verificationURL)
}


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

package main

import (
	"fmt"
	"os"

	"github.com/tencentcloud/tencentcloud-sdk-go-intl-en/tencentcloud/common"
	"github.com/tencentcloud/tencentcloud-sdk-go-intl-en/tencentcloud/common/errors"
	"github.com/tencentcloud/tencentcloud-sdk-go-intl-en/tencentcloud/common/profile"
	"github.com/tencentcloud/tencentcloud-sdk-go-intl-en/tencentcloud/common/regions"
	faceid "github.com/tencentcloud/tencentcloud-sdk-go-intl-en/tencentcloud/faceid/v20180301"
)

func GetWebVerificationResult(bizToken string) {
	// Set the TencentCloud API access key
	credential := common.NewCredential(
		os.Getenv("TENCENTCLOUD_SECRET_ID"),
		os.Getenv("TENCENTCLOUD_SECRET_KEY"),
	)
	cpf := profile.NewClientProfile()
	client, _ := faceid.NewClient(credential, regions.Singapore, cpf)
	request := faceid.NewGetWebVerificationResultIntlRequest()
	// Pass in the BizToken parameter
	request.BizToken = common.StringPtr(bizToken)
	response, err := client.GetWebVerificationResultIntl(request)
	if _, ok := err.(*errors.TencentCloudSDKError); ok {
		fmt.Printf("An API error has returned: %s", err)
		return
	}
	if err != nil {
		panic(err)
	}
	if response.Response.ErrorCode == nil {
		fmt.Print("the verification is uncompleted.")
		return
	}
	errorCode := *response.Response.ErrorCode
	errorMsg := *response.Response.ErrorMsg
	if errorCode == 0 {
		// Verification passed
		fmt.Print("Success")
	} else {
		// Verification failed
		fmt.Printf("Fail: %s\\n", errorMsg)
	}
}


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;
}

Previous Topic: Integration ProcessNext Topic: HTML5 Compatibility and Mode Switch Description

Help and Support

Was this page helpful?

Help us improve! Rate your documentation experience in 5 mins.

Feedback