Customer onboarding (KYC) integration with UI

📁 Table of Contents

ℹ️ Introduction

This documentation will guide you through the Customer Onboarding (KYC) process with a full Ondato APIs integration.

🔶 Integration workflow

🐾 Integration steps

1. Make sure that you have a valid access token to access our APIs. More information on how to obtain one you can find here.

2. Create Identity Verification (IDV) by making POST request to IDV API - /v1/identity-verifications/ endpoint with setupId in the request body. More information about setups you can find here.
   Request example:

   {
     "externalReferenceId": "123",
     "registration": {
       "dateOfBirth": "2021-01-14",
       "email": "John@email.com",
       "firstName": "John",
       "lastName": "Johnson",
       "middleName": "Adam",
       "personalCode": "1214148111000",
       "phoneNumber": 370624515141,
       "countryCode": "LT"
     },
     "setupId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
   }

   Response example:

   {
     "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
   }

3. Generate IDV URL with identity verification id that was received in step #2. The URL must be in the following format:

   1. Production: https://idv.ondato.com/?id={id}

   2. Sandbox: https://sandbox-idv.ondato.com/?id={id}

   Production URL example: https://idv.ondato.com/?id=02c99769-51a5-4174-aa5b-3fa0c2e6bfef
   This URL can be shared with your customers so that they can complete KYC identification.

4. Track customer onboarding progress by receiving webhooks.
   KycIdentification webhooks will contain payload information from the Ondato Kyc Identification API resource /v1/identifications/{id}.
   Idv webhooks will contain payload information from the Ondato IDV API resource /v1/identity-verifications.
   To learn more about Ondato webhooks and how to start receiving them please see the following page: Webhooks.

5. Retrieve data about Identity Verification (IDV) by making a GET request to IDV API - /v1/identity-verifications/{id} endpoint.
   Response example:

   {
     "id": "89e50d98-c556-4818-8562-3cd98608bf09",
     "status": "Completed",
     "applicationId": "0736cd0c-5a8d-45f8-a000-b5205ff4922d",
     "createdUtc": "2022-09-29T14:17:19.171Z",
     "modifiedUtc": "2022-09-29T14:19:42.973Z",
     "setup": {
       "id": "0f60f6f8-8e73-4873-b2ee-e02275994a77",
       "versionId": "67613d97-37c9-4230-ad87-e2227cdb4f78"
     },
     "step": {
       "kycIdentification": {
         "id": "9ac12241-4333-46b0-8aa6-0b49e5444539"
       },
       "consent": {
         "isConsented": true,
         "consentedUtc": "2022-09-29T14:18:11.684Z"
       }
     }
   }

6. Retrieve KYC data by making a GET request to Kyc Identification API - /v1/identifications/{id} endpoint to retrieve KYC identification details.
   Response example:

   {
     "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
     "applicationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
     "createdUtc": "2022-09-29T14:35:12.907Z",
     "setup": {
       "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
       "versionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
     },
     "identityVerificationId": "1dbb6d1d-0596-4247-9b37-879e44c53ddc",
     "status": "Awaiting",
     "statusReason": "MissingDocumentPhoto",
     "isCrossChecked": true,
     "document": {
       "fullName": "John Adam Jones",
       "firstName": "John",
       "middleName": "Adam",
       "lastName": "Jones",
       "documentNumber": "PU2343443343",
       "dateOfIssue": "2000-02-03",
       "dateOfExpiration": "2000-02-03",
       "dateOfBirth": "2000-02-03",
       "personalCode": "199202030202",
       "address": "string",
       "nationalityIso3": "LTU",
       "countryIso3": "LTU",
       "countryStateIso2": "GR",
       "gender": "Male",
       "type": "IdCard",
       "mrzVerified": true,
       "category": "B",
       "files": [
         {
           "createdUtc": "2022-09-29T14:35:12.907Z",
           "fileId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
           "fileName": "identity_file.jpeg",
           "fileExtension": "jpeg",
           "part": "Front",
           "fileType": "DocumentPhoto"
         }
         ....

🔀 Integration sequence diagram