KYC Web SDK

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.

  • The SDK supports two operational modes to accommodate different use cases:

    • Create mode initiates a new verification session, allowing full customisation of the verification journey through configurable options.

  • Retrieval mode enables access to an existing verification session, allowing users to resume a session that was newly created or previously initiated.
  • With a customised 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`

  1. 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)
  2. Request parameters in header
ParameterRequiredValue
AuthorizationRequired

Basic base64 of client_id:secret


Note: Truuth team will share this information

Content-TypeRequired'application/x-www-form-urlencoded'
  1. Request parameters in body (Form URL Encoded)

    ParameterRequiredValue
    grant_typeRequiredclient_credentials
    client_idRequiredtruuth team will share this
    scopeRequiredwebsdk/websdk:run
  2. 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.

The SDK operates in two distinct modes—create and retrieval—based on the presence of a verification ID in the configuration object:

  • Retrieval mode: When a verification ID is included in the configuration object, the SDK enters retrieval mode. In this mode, any additional settings provided in the config field are disregarded, and the SDK loads the verification journey associated with the provided ID.
  • Create mode: If no verification ID is supplied, the SDK defaults to create mode. In this case, the config object is required to initialize a new verification session and define its behavior and appearance. 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.

The customised configuration used to initialise the SDK. The JSON object schema is defined as follows:

ParameterTypeRequiredDescription
tenantStringRequiredTenant alias with all letters in lower case.
tokenStringRequiredThe access token required for calling SDK endpoints. Refer above How to generate the token section
apiUrlStringRequiredThe 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.
widthStringOptionalThe width of the SDK element in percentage.
heightStringOptionalThe height of the SDK element in percentage.
verificationIdStringOptionalDetermines whether the SDK operates in retrieval mode. If provided, the SDK loads an existing verification session, and the config field will be ignored.
restartSessionbooleanOptionalWhen set to true, this attribute instructs the SDK to initiate a new verification session rather than continuing a previous one. This is particularly helpful for guaranteeing a clean restart in each verification flow during retrieval mode.
timeoutNumberOptionalThe 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. In create mode, if not provided, the SDK will look for this value in the config object.
timeoutMessageStringOptionalA 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. In create mode, if not provided, the SDK will look for this value in the config object.
configObjectConditionally RequiredRequired when creating a new verification session (create mode). Defines the behavior and appearance of the SDK. Ignored if verificationId is present. Refer to the 'Configuration' section for detailed properties and values.

Configuration

ParameterTypeRequiredDescription
identityOwnerObjectRequiredAttributes are listed below
emailStringOptional / Required

The customer's email id to save as part of the verification record
If mobileNumber not passed then email becomes mandatory.
Request should have either email or mobileNumber

givenNameStringOptionalThe customer's legal given name, also known as the first name.
familyNameStringOptionalThe customer's legal family name, also known as the last name or surname.
middleNameStringOptionalThe customer's legal middle name.
genderStringOptionalThe gender of the customer can be specified using 'M' for male, 'F' for female, or 'O' for others.
mobileNumberStringOptional / Required

The customer's contact number.
If email not passed then mobileNumber becomes mandatory.
Request should have either email or mobileNumber

dateOfBirthStringOptionalThe customer's date of birth in the format "YYYY-MM-DD".
externalRefIdStringOptionalThe reference ID. Please enter only alphanumeric characters.
optionsObjectOptionalAdditional options for customisation. Please refer to the Options section for more details on the properties and their values.

Options

Custom Framework

ParameterTypeRequiredDescription
channelStringOptional

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.

frameworkTypestringOptional

Specify the type. Possible values are:
CUSTOM – to use custom framework
PRE_CONFIGURED – to use pre-defined framework (specify the framework code in proofingFrameworks)

proofingFrameworksString[]Optional

Configured as part of your subscription. The service picks the first proofing framework by default. Contact Truuth to get the list applicable to your subscription and use the exact value.

customFrameworkobjectOptionalRefer to the custom framework section. Mandatory when frameworkType is CUSTOM.
timeoutNumberOptional

Time in seconds to wait for the verification result. Default is 60 seconds. If the result is not received within this time, it will be considered timed out.

timeoutMessageStringOptional

Custom message shown if verification takes too long. Defaults to the SDK's built-in message if not set.

showWelcomePageBooleanOptional

Show the Welcome page in the Truuth KYC app. Set to false to skip. Default is true.

showTermsAndConditionsPageBooleanOptional

Show the Terms and Conditions page in the Truuth KYC app. Set to false to skip. Default is true.

showSkipDocumentButtonBooleanOptional

Visible when set to true, hidden if false. Defaults to tenant configuration if not provided.

sanctionsAndPepCheckRequiredBooleanOptional

Enables a detailed background check (e.g., for employment). Defaults to false.

businessVerificationRequiredBooleanOptional

Enables company credit and public record verification using ACN. Pulls data from Equifax. Defaults to false.

identityOwnerCheckSourcestringOptional

Security Check

AttributeTypeRequiredDescription
nameStringRequired

Below is the list of checks that can be performed as part of the proofing check. One or more checks can be added as needed:
faceMatchCheck
dobMatchCheck
nameMatchCheck
documentRecencyCheck

requriedBooleanRequired

Default value is true.

numberOfDaysNumberOptional

Applicable only for documentRecencyCheck.
This value is used to determine if the submitted document is recent. For example, if set to 30, the check will fail if the document is older than 30 days.

promptUserBooleanOptional

Applicable only for documentRecencyCheck.
Allows the user to confirm 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.
TypeBodyComments
VERIFICATION_CREATEDFirst event in the verification lifecycle. Broadcast only in create mode. Not emitted in retrieval mode, since the verification is assumed to be created outside the SDK.
VERIFICATION_STATUS_CHANGED
{
  "currentStatus": "string",
  "previousStatus": "string"
}
Emitted on every status transition (e.g., new → InProgress, InProgress → processing, processing → done).
VERIFICATION_SUBMISSION_STARTEDIndicates that the user has started the submission journey
TERMS_AND_CONDITION_ACCEPTEDIndicates the user has accepted the terms and conditions.
TERMS_AND_CONDITION_DECLINEDIndicates the user has declined the terms and conditions.
VERIFICATION_SUBMISSION_ABORTED
{
  "abortedReasonCode": "string"
}
Emitted if the submission process is aborted. Refer to Aborted Reason Codes for details.
VERIFICATION_SUBMISSION_COMPLETEDIndicates that the user has completed the submission process
VERIFICATION_PROCESSING_STARTEDMarks the beginning of verification processing once the submission process completed.
VERIFICATION_PROCESSING_TIMEOUTIndicates the processing phase has timed out based on the amount of time to wait for the verification result.
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"
                  }
                ]
              }
            ]
          }
        ]
Indicates that the verification process is complete, either because all processing steps were successfully completed or because the user declined the terms and conditions during the submission flow.
ERROR
{
  "name": "string",
  "message": "string"
}
Emitted when an error occurs during the SDK journey. Refer to Error Codes for specific cases.
  • Aborted Reason Codes
NameDescription
UserRequestedIf 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
NameMessageComments
InvalidTenantErrorTenant not found.
UnauthorizedErrorUnauthorized AccessIt can be replicated by passing an invalid token in create mode, or by providing a mismatched token and verification ID pair in retrieval mode.
BadRequestErrorInvalid request. Please check SDK parameters provided. [(Parameter: <param_name>)]
ErrorIt looks like something went wrong. Please try again and if the problem still persists please contact your service provider.
UnsupportedPlatformErrorSorry, 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.
JailBreakDetectedErrorThis 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.
AppUpdateErrorIt 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'.