Introduction

Decentro's CKYC Bulk Upload product is an abstraction over CKYC's Upload via a simple API. The solution lets customers seamlessly push bulk users and their documents via a single API hit.

Decentro will perform all the validations, image processing, image compression, batch building, connecting to the Financial Institution's SFTP server, and uploading the users to CKYC in the format recommended by them.

Additionally, Decentro will also parse all stage-wise and periodic response files from CKYC. We will send you an email whenever an upload is pending on the CKYC portal, after which you are expected to approve the upload checker of the batch. Decentro also sends detailed reports about approved and rejected updates from CKYC post approval from the checker.

Lastly, to add more touch points to the entire flow described above, Decentro's CKYC Bulk Upload solution also comes with status check APIs, both at the transaction level as well as the line item level (whether it's a batch of individuals or legal entities).

In short, you get to combine the best of both worlds, with the simplicity of an API interface and the stability of an SFTP connection.

Decentro handles the SFTP connection in the backend so that you don't have to worry about pushing and polling files from SFTP, and does all the heavy lifting required to parse the API request payload into CKYC's format.

This documentation is geared towards members of business and product teams and gives you a gist on how to get started with the CKYC Upload solution, steps to take post-go-live, and frequently asked questions.

Product Flow

The CKYC Upload API for individuals and legal entities is segregated into 5 high-level flows that the batch processor takes while attempting to create a CKYC Record. The five flows are as follows:

1. A recent KYC record is pushed with a CKYC ID
2. An older KYC record is pushed with a CKYC ID
3. A new KYC record is pushed without a CKYC ID
4. A recent KYC record is pushed without a CKYC ID
5. An older KYC record is pushed without a CKYC ID

The following diagram shows the high-level segregation of the product flows.

Case 1: A recent KYC record is pushed with a CKYC ID

The flow for a recent KYC record pushed with a CKYC ID is as follows:

1. The merchant hits the CKYC Upload API for individuals or legal entities with a batch of line items.
2. Decentro proceeds to perform validations and rate limit checks.
3. A CKYC search is performed using the CKYC ID provided in the input.
4. The record contains a KYC verification date that is more recent than the CKYC record.
5. Update is pushed since the record already exists but a more recent version is provided.

Case 2: An older KYC Record is pushed with a CKYC ID

The flow for an older KYC record pushed with a CKYC ID is as follows:

1. The merchant hits the CKYC Upload API for individuals or legal entities with a batch of line items.
2. Decentro proceeds to perform validations and rate limit checks.
3. A CKYC search is performed using the CKYC ID provided in the input.
4. The record contains a KYC verification date that is older than the CKYC record.
5. The CKYC Search result is pushed to the merchant via a callback for audit purposes.

Case 3: A new KYC Record is pushed without a CKYC ID

The flow for a new KYC record pushed without a CKYC ID is as follows:

1. The merchant hits the CKYC Upload API for individuals or legal entities with a batch of line items.
2. Decentro proceeds to perform validations and rate limit checks.
3. A CKYC search is performed using other parameters in the request such as PAN.
4. The CKYC Search fails indicating that this record does not exist in the CKYC records registry.
5. The record is pushed to CKYC on the creation pipeline.

Case 4: A recent KYC Record is pushed without a CKYC ID

The flow for a recent KYC record pushed without a CKYC ID is as follows:

1. The merchant hits the CKYC Upload API for individuals or legal entities with a batch of line items.
2. Decentro proceeds to perform validations and rate limit checks.
3. A CKYC search is performed using other parameters in the request such as PAN.
4. The CKYC Search succeeds indicating that this record exists in the CKYC records registry.
5. The record contains a KYC verification date that is more recent than the CKYC record.
6. Update is pushed since the record already exists but a more recent version is provided.

Case 5: An older KYC Record is pushed without a CKYC ID

The flow for a recent KYC record pushed without a CKYC ID is as follows:

1. The merchant hits the CKYC Upload API for individuals or legal entities with a batch of line items.
2. Decentro proceeds to perform validations and rate limit checks.
3. A CKYC search is performed using other parameters in the request such as PAN.
4. The CKYC Search succeeds indicating that this record exists in the CKYC records registry.
5. The record contains a KYC verification date that is older than the CKYC record.
6. The CKYC Search JSON is pushed to the merchant via a callback for audit purposes.

Overall Product Flow Diagram

Please note: The above flow diagram only encapsulates those scenarios where the batch that has been pushed by the merchant to Decentro has passed all Decentro-level validations and rate limit checks.

Integration Guide

Step 1: Get Testing Credentials

What are Testing credentials?

These are credentials provided to each platform based on their requirements and the module they opt to test out. You can access the APIs of the respective modules that you're interested in and have a discussion with our business team.

With the credentials, you can test our APIs in the same way as your live credentials and check out how our APIs provide responses on a test environment called 'Staging'. These credentials are designed to work in this environment only and production credentials will be shared separately post-closure of formalities.

How do I test the APIs?

While you are onboarded on the test environment ('Staging') by our team, you will receive the credentials for the modules you've chosen to go with. If you haven't got your testing credentials yet, you can get them by signing up here.

You'll get the below important credentials for each module that you choose -

Please note that the credentials are unique to a platform and should not be shared within the organization without consent or with any external partners.

2. JWT

JWT stands for JSON Web Token. It is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object.

• Customers can generate JWT using our Auth API with various grant types in the request body.
• Customers can pass the grant_type as
  • client_credentials
  • refresh_token
  • user_credentials
• The JWT token is valid for 15 minutes by default

Generate JWT with Client Credentials

Customers can generate JWT with Client Credentials -

Generate JWT with Refresh Token

Customers can generate JWT with Refresh Token -

Generate JWT with User Credentials

Customers can generate JWT with User Credentials -

How to use JWT in Decentro APIs?

Once customers generate JWT, they can use this instead of client_id and client_secret in API Authorization.

• Customers can pass JWT in headers instead of client_id and client_secret to access the API
• All our APIs will work with both the methods, Client Credentials, and JWT

Step 2: Log in to the CKYC Portal

• You need a Windows System to log in to the CKYC Portal.
• Make sure a DSC reader utility is installed on your Windows system.
  • CERSAI recommends you use the utility linked on the Downloads Page. You can access the page here.
  • Please download the executable file marked under “Digital Signature Utility”
  • Install the executable and restart your computer.
• To log in to the CKYC Portal, please use Edge or Opera Browser.
• CKYC Portal requires you to be logged in using Internet Explorer only.
• You can open an Edge browser session in Internet Explorer mode using the steps mentioned below:
  • In the address bar for Microsoft Edge, type edge://settings/defaultbrowser and then click Enter.
  • Slide the Allow sites to be reloaded in Internet Explorer toggle to ON.
  • Restart Microsoft Edge.
  • For more information on the above, please refer to this link.

Step 3: Find your FI Code

The FI Code is found on the top right of the portal and is visible once you log in to the CKYC Portal. Please collect this code since this is important for the CKYC Upload integration.

Reference Screenshot:

Step 4: Create the Region and Branch Code

Note: The Branch and Region codes are NOT the codes mentioned on the top right of the portal. Instead, these have to be created manually by the user. The steps are discussed below:

1. First, go to the Region Master tab. Here you have to create an arbitrary Region Name and Region Code.
2. Second, go to the Branch Master tab. Here you will have a dropdown list that will let you select the Region you have created in step 1.
3. After selecting a region, create an arbitrary Branch Name and Branch Code. Make sure these are different from the Region Name and Region Code.

Reference Screenshots:

Step 5: Enable Decentro to perform a CKYC Search

Step 1: Log in to the CKYC Portal. Go to User Management. Hover over the option and click on the "Upload Public Key" menu (Illustrative image attached)

Step 2: Upload the public certificate received from Decentro.

Step 3: Whitelist the IP address that is provided by Decentro.

Step 6: Provide the following information

After performing the above steps, you will need to inform the Decentro team about the following details:

1. FI Code
2. Branch Code
3. Region Code
4. List of Emails that will get the updates

After this step, we will have everything necessary to go live. Please await a go-ahead from us for production access.

The next section provides a high-level overview of the API contracts. You can get more details regarding the technical specification of this product by checking out our API Reference for CKYC Upload.

API Contracts

📑 Request Contract

The requested contract for CKYC bulk upload will have the following parameters:

👍

Rule of Thumb

You must either send a list of individuals or a list of legal_entities only.

You cannot send both these fields in the same request because CKYC has different rules for creating a batch of different entities and mandates that a batch has either only a set of individuals or legal_entities.

Hence, to maintain simplicity and a clean interface, we have segregated CKYC Upload for Individuals and Legal Entities into 2 separate APIs.

🧑🏻 Upload Individuals

The following shows a sample request and response body for uploading individuals to the CKYC Record Registry. For more information on the parameters inside the individuals array, please refer to the Upload Individuals API for individuals.

👍

Baked-in Aadhaar Masking

Worried about the documents being uploaded to CKYC aren't masked properly?

Well, don't worry! The CKYC Upload API now automatically performs Aadhaar masking whenever the document submission type is OFFLINE_VERIFICATION.

{
    "reference_id": "12345",
    "consent": true,
    "purpose": "For bank account purpose",
    "verifier": {
        "name": "John Doe",
        "designation": "CEO",
        "employee_code": "123456789",
        "kyc_declaration_place": "Bangalore"
    },
    "individuals": [
        {
            "identifier": "1",
            "salutation": "MR",
            "name": "John Doe",
            "gender": "MALE",
            "date_of_birth": "YYYY-MM-DD",
            "location": {
                "address": "XXXXXXXXXXXXXXXXXXXX",
                "pincode": "XXXXXX"
            },
            "document_submission_type": "EKYC",
            "relative": {
                "salutation": "MR",
                "type": "FATHER",
                "name": "John Doe"
            },
            "documents": [
                {
                    "base64": "xxxx",
                    "type": "AADHAAR"
                },
                {
                    "base64": "xxxx",
                    "type": "PHOTOGRAPH"
                }
            ],
            "ids": [
                {
                    "id_number": "ABCDE1234F",
                    "type": "PAN"
                },
                {
                    "id_number": "XXXXXXXX1234",
                    "type": "VOTER_ID"
                }
            ]
        }
    ]
}

{
    "decentroTxnId": "DEC001",
    "status": "SUCCESS",
    "responseCode": "S00000",
    "message": "CKYC bulk upload has been initiated",
    "responseKey": "success_initiate_bulk_upload"
}

🏦 Upload Legal Entities

The following shows a sample request and response body for uploading legal entities to the CKYC Record Registry.

{
    "reference_id": "12345",
    "consent": true,
    "purpose": "For bank account purpose",
    "verifier": {
        "name": "John Doe",
        "designation": "CEO",
        "employee_code": "123456789",
        "kyc_declaration_place": "Bangalore"
    },
    "legal_entities": [
        {
            "identifier": "1",
            "consitution_type": "PARTNERSHIP_FIRM",
            "entity_name": "John Doe Partners",
            "incorporation": {
	            "place": "Bangalore",
	            "date": "YYYY-MM-DD",
	            "country_code": "IN"
            },
            "commencement_date": "YYYY-MM-DD",
            "location": {
                "address": "XXXXXXXXXXXXXXX",
                "pincode": "XXXXXX"
            },
            "related_individuals": [
                {
                    "type": "DIRECTOR",
                    "deletion_flag": false,
                    "salutation": "MR",
                    "name": "Jane Doe",
                    "ckyc_number": "XXXXXXXXXXXXXXX"
                }
            ],
            "document_submission_type": "CERTIFIED_COPIES",
            "documents": [
                {
                    "base64": "<base64>",
                    "type": "OFFICIALLY_VALID_DOCUMENT"
                },
                {
                    "base64": "<base64>",
                    "type": "CERTIFICATE_OF_INCORPORATION"
                }
            ],
            "ids": [
                {
                    "id_number": "ABCDE1234F",
                    "type": "OFFICIALLY_VALID_DOCUMENT"
                },
                {
                    "id_number": "XXXXXXXX1234",
                    "type": "CERTIFICATE_OF_INCORPORATION"
                },
                {
                    "id_number": "ABCDE1234F",
                    "type": "GSTIN"
                },
                {
                    "id_number": "XXXXXXXX1234",
                    "type": "PAN"
                }
            ]
        }
    ] 
}

{
    "decentroTxnId": "DEC001",
    "status": "SUCCESS",
    "responseCode": "S00000",
    "message": "CKYC bulk upload has been initiated",
    "responseKey": "success_initiate_bulk_upload"
}

⚡️Status Updates

Both Individuals and legal entities have similar GTS APIs and the response contracts are mentioned below.

📚 Bulk Transaction GTS

{
    "decentroTxnId": "XXXXXXX",
    "status": "SUCCESS",
    "responseCode": "S00000",
    "data": {
        "referenceId": "XXXXXX",
        "bulkDecentroTxnId": "XXXXXX",
        "individuals": {
            "requested": 10,
            "processed": 1,
            "successful": 9,
            "failed": 1,
            "pending": 0,
            "failedIdentifiers": [
                "123456789"
            ]
        },
        "stage": "BULK_CKYC_UPLOAD_RECORDS_UPLOADING_SUCCESSFUL",
        "status": "SUCCESS",
        "description": "Records Uploading Succeeded",
        "creationTimestamp": "XXXXXXXXX",
        "lastModificationTimestamp": "XXXXXXXXX"
    },
    "responseKey": "success_bulk_upload_status_extracted"
}

📗 Unit Entity GTS

{
    "decentroTxnId": "XXXXXXXX",
    "status": "SUCCESS",
    "responseCode": "S00000",
    "data": {
        "identifier": "123456789",
        "referenceId": "XXXXXX",
        "bulkDecentroTxnId": "XXXXXXXX",
        "stage": "RECORD_VALIDATION_COMPLETED",
        "remarks": "Accepted by CKYC Registry",
        "status": "PROCESSING",
        "description": "Record Validation Completed",
        "creationTimestamp": "XXXXXXXXXX",
        "lastModificationTimestamp": "XXXXXXXXXX"
    },
    "responseKey": "success_bulk_upload_entity_status_extracted"
}

Post Go-Live

You can manage the authorization in the “Bulk Upload Authorization” in the CKYC Portal as shown below.

CERSAI KYC Managmentment >> Bulk Upload Authorization

You can also view the successful SFTP bulk upload responses in the same place where you view regular bulk upload responses, in the “Bulk Upload Response” section.

If you are a financial institution that does not have CKYC credentials, we encourage you to use Decentro’s CKYC Upload without Native Setup as UAT testing and go live on your FI code. If you are interested in getting your own credentials, please refer to Appendix 1 and 2.

Appendix 1: How to get your own CKYC credentials?

The process for Financial Institutions (FIs) to register with the Central KYC Registry is long and tedious. If you are willing to go through this painstaking ordeal, then the process is as follows:

• Visit the website of CKYC here -> Central KYC (CKYC).
• Click to register a new FI registration.
• First, you have to add the details of an individual who is the “admin” in this case.
• Then, you have to enter the details of your financial institution.
• Provide the details of the regulating body you are registered with (RBI, SEBI, etc).
• Download the filled FI registration form and submit it along with the required documents.

Appendix 2: Documents required for CKYC credentials

• A Duly signed Institution Registration Form of the FI
• Licence, Certificate, and Notification issued by the regulator
• PAN card of the Financial Entity
• Corporate Identification number in case the Institution holds multiple Licences
• In the case of Co-Operative Banks or Societies, you need to submit a Registration Certificate issued by the concerned authority
• The Authorization letter from the competent authority for Admin Users should be signed by the Authorised Signatory/ Director
• Certified copy of the photo identity card of the user administrator issued by the respective institution
• Certified copy of any ID proof of the user administrator.