KYC Web SDK (v2)
Introduction
The KYC web SDK is a versatile component that allows you to easily handle verification submission process in your web application. The purpose of the SDK is to simplify the integration of our clients to the KYC app. Using the SDK customisable configuration, the end user would be able to complete the KYC process using either the mobile app or the web app.
How the SDK works
The main highlights of KYC web SDK are as follows:
- The KYC web SDK can be easily embedded in any web application as a reusable web component, declared just like any other HTML element. By using the SDK as an embedded component, the entire journey can be handled within your own domain without the need for redirection to a new domain.
- With a customized configuration object, you can set up the SDK according to your preferences. For example, you can determine the dimensions of the SDK placeholder to make it fill the entire screen or give it a partial view on your page.
- By providing a channel name (mobile or web) in the SDK configuration data, the end user can proceed with the verification submission process either through a web browser or by installing the KYC mobile app on their phone.
- The SDK event broadcast is a useful tool that provides visibility into user activity from the beginning to the end of the verification submission journey. It allows you to respond to user interactions during the verification submission journey by implementing a desired event handler.
SDK Integration Guide
Integrating the KYC Web SDK into your web application is a simple and straightforward process. You can follow the integration steps outlined in the following recipe:
How to generate the token
Note: To use the token service, please contact truuth team to setup the same before following the below step in your code`
-
Use the below endpoint to generate the temporary token and to use the same in below SDK initialisation flow
Access token endpoint: https://XXXX-prod.auth.ap-southeast-2.amazoncognito.com/oauth2/token
Method : POST
Authorization: BASIC
Note : the alias ‘XXXX’ in the access token URL needs to be replaced with the alias of your tenancy
(where ‘XXXX’ is the alias name) -
Request parameters in header
Parameter Required Value Authorization Required Basic base64 of username:password
Note Truuth team will share this informationContent-Type Required Must always be 'application/x-www-form-urlencoded' -
Request parameters in body (Form URL Encoded)
Parameter Required Value grant_type Required client_credentials client_id Required truuth team will share this scope Required websdk/websdk:run -
Note: Store the username and password into your backend service and call this token service. Then pass the token back to frontend to send the same to the SDK initialisation.
How to initialise the SDK
To initialise the SDK, you can use the truuthKYCWebSdk.init(config) method, which takes a configuration JSON object as input.
In the config object, you can provide specific values for the properties based on your requirements. Adjust the property names and values accordingly to customise the initialisation of the SDK for your web application.
- config (JSON Object): The customised configuration used to initialize the SDK. The schema of the config JSON object is defined as follows:
| Parameter | Type | Required | Description |
|---|---|---|---|
| tenant | String | Required | Tenant alias with all letters in lower case. |
| token | String | Required | The access token required for calling SDK endpoints. Refer above How to generate the token section |
| apiUrl | String | Required | The base URL used for the verification submission process. Please set https://portal.api.au.truuth.id/kyc/ as the value for the AU region and https://portal.api.eu.truuth.id/kyc/ for the EU region. Note: Replace "au" and "eu" with the appropriate region code. |
| width | String | Optional | The width of the SDK element in percentage. |
| height | String | Optional | The height of the SDK element in percentage. |
| config | Object | Required | The configuration object containing additional settings for the SDK initialization. Please refer to the 'Configuration' section for more details on the properties and their values. |
Configuration
| Parameter | Type | Required | Description |
|---|---|---|---|
| identityOwner | Object | Required | Attributes are listed below |
email | String | Required | The customer's email id to save as part of the verification record |
givenName | String | Optional | The customer's legal given name, also known as the first name. |
familyName | String | Optional | The customer's legal family name, also known as the last name or surname. |
middleName | String | Optional | The customer's legal middle name. |
gender | String | Optional | The gender of the customer can be specified using 'M' for male, 'F' for female, or 'O' for others. |
mobileNumber | String | Optional | The customer's contact number. |
dateOfBirth | String | Optional | The customer's date of birth in the format "YYYY-MM-DD". |
| externalRefId | String | Optional | The reference ID. Please enter only alphanumeric characters. |
| options | Object | Optional | Additional options for customisation. Please refer to the 'Options' section for more details on the properties and their values. |
Options
| Parameter | Type | Required | Description |
|---|---|---|---|
| channel | String | Optional | Specifies the channel for the verification submission process. Possible values include "MOBILE" for the mobile app channel and "WEB" for the web app channel. If provided, the end user will proceed with the verification submission either through the web browser or by installing the KYC mobile app on their phone. |
| frameworkType | string | Optional | Specify the type. possibile values are,CUSTOM - to use custom frameworkPRE_CONFIGURED - to use pre-defined framework, specify the framework code in proofingFrameworks |
| proofingFrameworks | String [] | Optional | This is configured as part of your subscription. This is an optional field. Service will pick the first proofing framework by default. Please contact Truuth to get the list of proofing frameworks as per your subscription and you can send the exact value here. |
| customFramework | object | Optional | Refer the custom framework section below. This will be mandatory when you choose framework type as CUSTOM |
| timeout | Number | Optional | The amount of time in seconds to wait for the verification result. The default value is 60 seconds. If the result is not received within this timeout, the process will be considered as timed out. |
| timeoutMessage | String | Optional | A custom message to be displayed if the verification processing takes longer than expected. If no value is set, the SDK will use the default message. |
| showWelcomePage | Boolean | Optional | true if the identity owner should see the Welcome page in the truuth KYC app otherwise set it to false. Default is true. |
| showTermsAndConditionsPage | Boolean | Optional | true if the identity owner should see the Terms and conditions page in the truuth KYC app otherwise set it to false. Default is true. |
| showSkipDocumentButton | Boolean | Optional | Will be visible when this property is set to true, hidden when it set to false. If no value is passed then it uses the default value of the tenant configuration. |
| sanctionsAndPepCheckRequired | Boolean | Optional | Wish to do a more detailed investigation of a user’s background, mainly for employment purposes. After verifying a person’s identity, this check does the following searches. Defaults to false. |
| businessVerificationRequired | Boolean | Optional | A Company Enquiry product provides the credit records of a company together with public record information, ASIC data as it exists on the Veda database, plus fresh PPSR Grantor Search information on Companies. The user needs to supply an ACN so we can use it to retrieve the report from Equifax. Defaults to false. |
| identityOwnerCheckSource | string | Optional |
Custom Framework
| Parameter | Type | Required | Description |
|---|---|---|---|
| name | String | Optional | Name of the framework Maximum length shouldn't be greater than 50 |
| description | String | Optional | Brief decription of this framework and the same will be displayed in welcome page of KYC Maximum length shouldn't be greater than 500 |
| proofingType | Required | ||
code | String | Required | Value should be IDENTITY_PROOFING |
name | String | Required | display name of the proofing |
| faceMatchCheck | Object | Optional | Attributes are listed below |
requried | Boolean | Optional | default value is true |
liveness | Boolean | Optional | default value is true |
| minNumberOfDocumentsRequired | number | Optional | Number of documents expected from the user to do the verification default value is 1 |
| allowedDocuments | Object[] | Attributes are listed below | |
displayName | String | Required | Friendly display name. Same will be display for the KYC users to select the document |
documentType | String | Required | Reffer Supported document API |
pageCount | number | Required | number of pages for the document to be scanned or supplied |
countryCodes | String [] | Required | Reffer Supported document API Can add multiple country codes for document type. ANY for allowing all countries |
securityChecks | Object[] | Optional | List of checks that requires for this document. This is an optional field. Default will be based on the truuth document type configuration Reffer below section for schema |
Security Check
| Attribute | Type | Required | Description |
|---|---|---|---|
| name | String | Required | Below are the list of check can be performed as part of proofing check, can add one or more checks as per need.faceMatchCheckdobMatchChecknameMatchChecknameMatchCheckdocumentRecencyCheck |
| requried | Boolean | Required | default value is true |
| numberOfDays | Number | Optional | This property is applicable only for documentRecencyCheck In background, recencey check will be performed based on this value. If the number of days her is 30 then check will mark has Fail when submitted document is not less than 30 days |
| promptUser | Boolean | Optional | This property is applicable only for documentRecencyCheck This allows user to confirm the document recency during KYC submission |
Logging Event Information
As mentioned, the SDK Event broadcast helps provide visibility into user activity from the beginning to the end of the verification submission journey and allows you to respond to user interactions in the verification submission journey by implementing a desired event handler in your code.
The "detail" property of each event provides details about that event. The fields of the "detail" property dispatched by the SDK are as follows:
- type: It specifies the main event types triggered during the verification submission process. You can find a full list of event types in the following table.
- tenant: It indicates the tenant alias on which the SDK has been set up.
- verificationId: This can be transaction identifier.
- timestamp: It indicates event's creation date.
- body: This is an optional field that provides additional details about the event type. You can find more information about the body structure in the following table.
| Type | Body | Comments |
|---|---|---|
| VERIFICATION_STATUS_CHANGED | { "currentStatus": "string", "previousStatus": "string" } | |
| VERIFICATION_CREATED | ||
| VERIFICATION_SUBMISSION_STARTED | ||
| VERIFICATION_SUBMISSION_COMPLETED | ||
| VERIFICATION_SUBMISSION_ABORTED | { "abortedReasonCode": "string" } | Please note that the specific aborted reason codes and their meanings can be found in the 'Aborted Reason Codes' section, which provides more details regarding the possible reasons for the verification submission being aborted. |
| ERROR | { "name": "string", "message": "string" } | Please refer to 'Error Codes' section for more details. |
| VERIFICATION_PROCESSING_STARTED | ||
| VERIFICATION_COMPLETED | [ { "proofingType": { "code": "string", "name": "string" }, "proofingStatus": string, "userBehaviourChecks": [{ "name": "string", "type": "string", "status": "string" }], "documents":[{ "status": "string", "securityChecks":[{ "name": "string", "type": "string", "status": "string" }] }] } ] | |
| TERMS_AND_CONDITION_ACCEPTED | ||
| TERMS_AND_CONDITION_DECLINED | ||
| VERIFICATION_PROCESSING_TIMEOUT |
- Aborted Reason Codes
| Name | Description |
|---|---|
| UserRequested | If the user taps on 'Come back later' during the KYC submission process, an event of type "VERIFICATION_SUBMISSION_ABORTED" will be captured. The event object for this type would include the "abortedReasonCode" property, which indicates the reason for the verification submission being aborted. |
- Error Codes
| Name | Message | Comments |
|---|---|---|
| InvalidTenantError | Tenant not found. | |
| UnauthorizedError | Please check your token and make sure your token has not been expired. | |
| BadRequestError | Invalid request. Please check SDK parameters provided. [(Parameter: <param_name>)] | |
| Error | It looks like something went wrong. Please try again and if the problem still persists please contact your service provider. | |
| UnsupportedPlatformError | Sorry, your operating system is not supported. This probably means you have an old phone, or have not updated your phone’s software. Please update and try again, or try on a newer phone. | It can be replicated by trying KYC web invitation on Safari < 13.0. |
| JailBreakDetectedError | This device is jailbroken or rooted. For security reasons, you can't use this app. If you are using Android, you may have Developer Options turned on. Please check your Settings and turn them off. | It can be replicated by trying KYC mobile invitation on a jailbroken / rooted phone. |
| AppUpdateError | It looks like your version of the app is out of date. Please uninstall Truuth ID and start again by clicking on the link in your email. | It can be replicated by trying KYC mobile invitation using an old version of mobile app installed on the phone. |
SDK Completion Scenarios and Broadcast Events
The timeout allows the client to move the user onto next screens in cases where the result is not yet received. The timeout is the ending of SDK connection to the truuth backend and no more interaction is expected so, it is upto the client to decide if they wait for the result however long it is, or if after the timeout they move the use on and then control the experience to take further actions within their own web app. The client can then wait for the results from the callback to further inform their flow.
The SDK finishes working in one of the following situations:
1- Getting the result from backend -> broadcasting VERIFICATION_COMPLETED
2- Not getting any results from backend and timeout -> broadcasting VERIFICATION_PROCESSING_TIMEOUT
3- Error -> broadcasting ERROR
4- Come back by user -> broadcasting VERIFICATION_SUBMISSION_ABORTED (The event is broadcast when the user tries 'Come back later' option in the middle of verification submission journey and the client can move the user onto next screens in their own web site.)
Mobile and Desktop Browser Support
The KYC Web SDK supports the following browsers on different platforms:
- iOS: iOS Safari (version >= 13.0) and Chrome.
- Android: Chrome and Samsung Internet browser.
- Desktop: Firefox, Chrome, Samsung Internet, and Safari.
Please ensure that the specified browser versions are met for optimal compatibility and functionality with the KYC Web SDK.
Compatibility and Versioning
If the channel is selected as "mobile" in the SDK configuration, the KYC mobile app needs to be installed on the end user's phone as the KYC app platform.
- The KYC mobile app is compatible with Android devices running version 5.0 and above, with android:minSdkVersion="21" and android:targetSdkVersion="33" specified.
- For iOS devices, the KYC mobile app is compatible with iOS version 11.0 and above.
Also, the latest version of KYC web SDK is '1.0'.
Updated 19 days ago