Customer Document Authentication / Verification
Procedures on the KYC verification implementation are as follows:
- Retrieve the KYC providers enabled for the program
- Start the SDK Verification Process
- Follow the links returned per response until all assigned KYC steps or KYC stages have been completed
Process Flow
Customer Document Verification
In regions where we are required to do digital verification of user documents, we leverage third parties with trusted records to handle the verification and authenticity checks of the documents which have been approved by the issuing partner for the region.
The entire flow is managed in an environment hosted by Roecny to ensure all the issuing requirements are met and managed properly.
This flow is susceptible to upgrades depending on requirements coming from issuing partners, but follows the basic outline as illustrated below.
Step 1: Info Screen
This is an interstitial screen which just displays a message to the user about the process getting initialized.
Step 2a: Country Selection Screen
Depending on the configuration of the program, the user might be shown a country selection screen to choose.
Step 2b: Document Selection Screen
This is a screen in which the user selects what kind of document they are choosing to perform the verification process.
Step 3: Document Upload Screen
This screen guides the user to upload the images required for the verification process as per the document type selected.
Step 3: Liveliness Verification Screen
This screen is where the user is prompted to take a selfie and perform liveliness checks as part of the verification process.
Step 4: Process In Progress Screen
This is the screen which is shown as an interstitial message after the activities required by the user are completed.
Web SDK UI Customization
As a part of the SDK flow, each partner has an option to customize the look and feel of the Web SDK screen—which includes text, buttons, links, icon background color, and popups.
To be able to customize the SDK, a list of supported UI values are offered which partners will pass on as customization parameters on the POST users/authentications/documents/process endpoint.
List of supported UI related parameters:
| Parameter | Description |
|---|---|
| font_family_title | Change font family on SDK screen titles |
| font_family_subtitle | Change font family on SDK screen subtitles |
| font_family_body | Change font family on SDK screen body |
| font_size_title | Change font size on SDK screen titles |
| font_size_subtitle | Change font size on SDK screen subtitles |
| font_size_body | Change font size on SDK screen body |
| font_weight_title | Change font weight on SDK screen titles (number format only, e.g., 400, 600) |
| font_weight_subtitle | Change font weight on SDK screen subtitles (number format only, e.g., 400, 600) |
| font_weight_body | Change font weight on SDK screen content (number format only, e.g., 400, 600) |
| color_content_title | Change text color on SDK screen titles |
| color_content_subtitle | Change text color on SDK screen subtitles |
| color_content_body | Change text color on SDK screen body |
| color_background_surface_modal | Change background color on SDK screen |
| color_border_surface_modal | Change color on SDK screen border |
| border_width_surface_modal | Change border width on SDK screen |
| border_style_surface_modal | Change border style on SDK screen |
| border_radius_surface_modal | Change border radius on SDK screen |
| color_content_button_primary_text | Change color of Primary Button text |
| color_background_button_primary | Change background color of Primary Button |
| color_background_button_primary_hover | Change background color of Primary Button on hover |
| color_background_button_primary_active | Change background color of Primary Button on click/tap |
| color_border_button_primary | Change color of Primary Button border |
| color_content_button_secondary_text | Change color of Secondary Button text |
| color_background_button_secondary | Change background color of Secondary Button |
| color_background_button_secondary_hover | Change background color of Secondary Button on hover |
| color_background_button_secondary_active | Change background color of Secondary Button on click/tap |
| color_border_button_secondary | Change color of Secondary Button border |
| color_content_doc_type_button | Change Document Type Button text color |
| color_background_doc_type_button | Change background color of Document Type Button |
| color_border_doc_type_button | Change color of Document Type Button border |
| color_border_doc_type_button_hover | Change color of Document Type Button border on hover |
| color_border_doc_type_button_active | Change color of Document Type Button border on click/tap |
| color_background_icon | Change color of the background circle of pictogram icons in the SDK |
| border_radius_button | Change border radius value of Primary, Secondary, and Document Type Option buttons |
| color_content_link_text_hover | Change Link text color |
| color_border_link_underline | Change Link underline color |
| color_background_link_hover | Change Link background color on hover |
| color_background_link_active | Change Link background color on click/tap |
| color_content_alert_info | Change warning popup text color |
| color_background_alert_info | Change warning popup background color |
| color_content_alert_info_link_hover | Change warning popup fallback Link background on hover |
| color_content_alert_info_link_active | Change warning popup fallback Link background on click/tap |
| color_content_alert_error | Change error popup text color |
| color_background_alert_error | Change error popup background color |
| color_content_alert_error_link_hover | Change error popup fallback Link background on hover |
| color_content_alert_error_link_active | Change error popup fallback Link background on click/tap |
| color_background_info_pill | Change background color of Cross Device, Camera/Mic Permissions screens' information header pill |
| color_content_info_pill | Change text color of Cross Device, Camera/Mic Permissions screens' information header pill |
| color_background_button_icon_hover | Change background color of Back, Close icon buttons on hover |
| color_background_button_icon_active | Change background color of Back, Close icon buttons on click/tap |
| color_background_button_camera_hover | Change background color of Live Selfie/Document Capture screens' Camera button on hover |
| color_background_button_camera_active | Change background color of Live Selfie/Document Capture screens' Camera button on click/tap |
Customer Document Authentication
In certain regions like Singapore and India where there is a national registry of customer demographic information and regulation permits verification against said registry as an allowed mode of customer diligence, we support authentication via said registry also.
Customer KYC Lifecycle Management
After the initial verification has been completed, there are certain scenarios which would trigger a re-verification process. This includes and may not be limited to:
- Customer record getting flagged for certain triggers
- Customer's documents on record reaching expiry
- Issuing Partner rejects the KYC because the documents verified are flagged by the compliance team and require re-verification
Partners are expected to handle these updates and ensure the process is re-initiated for the affected customers by re-collecting the information and re-triggering the customer verification process as highlighted above.
Webhooks
To better facilitate the integration experience of partners, Roecny provides webhooks to notify consumers or partners on the changes of a user's KYC status. These are POST requests to the partner's server that are sent depending on the event. The webhook structure contains the details of the webhook event.
Partners can create and configure webhooks and should acknowledge the success by responding with an HTTP status of 200.
Below are the events to be configured for the webhook:
| Code | Name | Remarks |
|---|---|---|
ACCOUNT.KYC.VERIFICATION_START |
KYC Initiate Verification Started | This notifies the program in the event the user completes the SDK form |
ACCOUNT.KYC.VERIFICATION_COMPLETED |
KYC Initiate Verification Success | This notifies the program in the event the external KYC service provider verification process is completed |
ACCOUNT.KYC.VERIFICATION_FAILED |
KYC Initiate Verification Failed | This notifies the program in the event a failure happens on any process after a verification is completed |
ACCOUNT.KYC.VERIFICATION_APPROVED |
KYC Verification Approved | This notifies the program in the event that the KYC status of the user is updated to approved |
ACCOUNT.KYC.VERIFICATION_REJECTED |
KYC Verification Rejected | This notifies the program in the event that the KYC status of the user is updated to rejected along with a reject code |
Alternatively, to retrieve the latest status of the user, partners can call Get KYC Status Endpoint.
KYC Failures
The process of review is an ongoing process in addition to the initial approval process. As part of this process, on an ongoing basis based on occurrences of suspicious activity, outdated documents, or as part of periodic audits, the user can be downgraded to a pre / lite KYC status.
Both as part of initial verification and subsequent rejections, this information is communicated to API consumers as part of the webhook.
The reason for the rejection is communicated as part of the webhook. The reject reason can be an array of reason codes highlighted below:
| Code | Description |
|---|---|
DOCUMENT_QUALITY |
The documents uploaded are of bad quality / cropped out of frame |
DOCUMENT_AUTHENTICITY |
The documents submitted are suspected to be not genuine |
DOCUMENT_DEMOGRAPHIC_MATCH |
The demographic information of the user doesn't match the information extracted from documents |
LIVELINESS_AUTHENTICATION |
The liveliness check of the user has failed |
EXPIRED_DOCUMENTS |
The documents information present in the system have expired |
UNSPECIFIED |
The reason for rejection is reserved for the time being |
FAQs
List of commonly asked questions on the KYC integration:
1. Does the user have the option to upload documents from Phone Gallery or files?
For the document upload flow from the native SDK, we require a real-time capture of documents; upload from gallery is not supported.
2. I am not clear about the user flow from step 2 (choosing country) to step 3 (camera opens up). What is the action in step 2 that redirects users to step 3?
As soon as you select the country, it will navigate to the document capture screen. After selecting the relevant document type, you will be prompted to the document upload screen.
3. How are device permissions managed?
When the camera is invoked for the first time, the user is prompted for permission. Once granted, the SDK can utilize the camera functionality.
4. Is there any upper limit of file size which will get uploaded? If yes, where are we communicating to users?
For the Native SDK, the user is not allowed to upload images; the SDK captures the image and is responsible for down-sampling to the relevant sizes. In scenarios where image upload is supported, the image size is restricted to between 32KB - 8MB and would be communicated to the user inline in the relevant view.
5. What are the corner cases of photo upload or document upload getting failed? How are we handling it?
Wrong document, blurry image, text in the document is not clear—these are reasons for document upload rejection. The SDK performs real-time checks, and if an issue is detected, error messages are displayed to users on the relevant screen within the SDK.
Note that there is also a server-side check which evaluates the authenticity of the documents in detail. These are managed asynchronously via webhooks for the customer verification status update.
6. In the screen where we are asking for the country, how does the field for suggested country work? When the user clicks on the search bar, how does the UI change?
When the user clicks on the search bar, it lists the supported countries. In regions where multi-country issuance is not supported, the SDK will automatically omit this screen and optimize the user journey to route to the next applicable stage, i.e., the document upload.
7. What screen will appear when the final selfie is taken?
After the selfie, a final screen appears to inform the user that the document is submitted and in process. Then, the KYC verification will be processed in the background. Based on the webhooks, the consumer can choose how to handle the experience for the end-user.
8. How are we communicating to users on successful submission of documents? I don’t see any UI on that.
Once the document submission flow is completed, you are redirected to the in-progress screen. The system then triggers webhooks for communicating status updates asynchronously. The API consumer is expected to handle the events and end-user display and communication as per their design. Also, as part of initialization parameters, API consumers can define the redirect URI per the specs. When the user clicks the continue button on the status screen, they will be redirected as per the defined URI scheme.
9. Are there any upper thresholds on the number of times a user can retake a selfie/photo?
Currently, there is no threshold on user re-attempts, but restrictions or throttling may be imposed dynamically as risk rules are updated. API consumers are expected to handle this as part of the POST users/authentications/documents/process endpoint for the web SDK or as a callback event for the native SDK post-initialization.
10. When users drop off in the middle of the flow, can they start from where they left off, or do they have to start again?
Every time the user aborts, the process is terminated. The API consumer is expected to handle the event and reinitialize the process by calling the POST users/authentications/documents/process endpoint for the web SDK or reinitializing the native SDK.
11. When full KYC gets rejected, can users keep retrying indefinitely, or do you block users after a certain number of retries?
Currently, users can try again. However, as we optimize the platform, constraints might be added. The API consumer is expected to handle this as part of the POST users/authentications/documents/process endpoint for the web SDK or as a callback event for the native SDK post-initialization.