tencent cloud

Feedback

Integration Process

Last updated: 2024-12-04 16:55:39
    This document introduces the overall integration process of eKYC liveness detection and face comparison (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 liveness detection and face comparison (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.tencentcloud.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.ap-guangzhou.tencentcloudapi.woa.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.tencentcloud.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.ap-guangzhou.tencentcloudapi.woa.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);
    }
    
    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