—
–
/

to search

Introducing Setu Changelog Check it out ↗

Reading time — 5 minutes

Edit this page ↗

#eKYC API Quickstart

#Overview

This guide describes the implementation of our eKYC APIs. It allows you to create an eKYC request, which generates a verification URL. Once the aadhaar holder completes the Aadhaar verification process, the eKYC data can be retrieved.

You will need the following 2 APIs—

  • Create eKYC request- This lets you initiate an eKYC request.
  • Get eKYC request- This lets you check the status and data associated with the eKYC request.

Here is the information you would need for calling these APIs—

  • Sandbox URL—https://dg-sandbox.setu.co
  • Production URL—https://dg.setu.co
  • Headers—Contact support@setu.co for providing the credentials required to successfully call Setu APIs. This contains:
    • x-client-id
    • x-client-secret
    • x-product-instance-id
  • One time configuration
    • webhook_url
    • redirection_url (default, can be overridden per request)

#Create eKYC request

Call this API to create a unique request to get your customer started on the eKYC journey.

Your request has been processed successfully and a new eKYC request has been created.

Request
POST /api/ekyc/
            
{
  "webhook_url": "<client_webhook_url>" // Optional
  "redirection_url": "<client_redirection_url>"
}
Response

Use the request id in this response for all subsequent API calls.

{  
  "id": "0c624d3e-9cb0-4323-b468-d89092d7d305", // UUID4
  "status": "CREATED", // enum 'eKYC Request Status'
  "kycURL": "https://{base_url}/public/ekyc-web/0c624d3e-9cb0-4323-b468-d89092d7d305"
}

#Get eKYC request

Call this API to get the status and data (if the status is SUCCESS) of your eKYC request.

Response Type 1

In progress
Request
GET /api/ekyc/:request_id
Response
{
    "id": "2ac3191e-d5ef-4e99-9aef-4ad93e1b720d",
    "status": "CREATED",
    "kycUrl": "http://localhost:3100/v1/public/ekyc-web/2ac3191e-d5ef-4e99-9aef-4ad93e1b720d",
    "data": null
}

Response Type 2

Aadhaar verification done
Request
GET /api/ekyc/:request_id
Response
{
    "id": "0c624d3e-9cb0-4323-b468-d89092d7d305", // UUID4
    "status": "SUCCESS", // enum 'eKYC Request Status'
    "kycURL": "http://dg-ekyc.setu.co/public/ekyc-web/0c624d3e-9cb0-4323-b468-d89092d7d305"
    "data": {
        "aadhaar": {
            "name": "Ritesh Ujjwal",
            "dateOfBirth": "1989",
            "gender": "M",
            "address": {
                "careOf": "",
                "country": "India",
                "district": "ABC",
                "house": "",
                "landmark": "XYZ",
                "locality": "AAAAAA",
                "pin": "560001",
                "postOffice": "Bangalore",
                "state": "Karnataka",
                "street": "ABC Road",
                "subDistrict": "",
                "vtc": "my location"
            },
            "photo": "...base64...",
            "aadhaarNumber": "XXXXXXXX8888", // masked aadhaar number
            "generatedAt": "2024-03-22T15:18:35.269+05:30"
        },
        "xml": {
          "xmlBase64": "...base64..." 
        }
    }
}

#Webhook response

{  
    "event": "EKYC_DATA",
    "data": {
        "id": "...",
        "status": "SUCCESS",
        "aadhaar": {
            "name": "Ritesh Ujjwal",
            "dateOfBirth": "1989",
            "gender": "M",
            "address": {
                "careOf": "",
                "country": "India",
                "district": "ABC",
                "house": "",
                "landmark": "XYZ",
                "locality": "AAAAAA",
                "pin": "560001",
                "postOffice": "Bangalore",
                "state": "Karnataka",
                "street": "ABC Road",
                "subDistrict": "",
                "vtc": "my location"
            },
            "photo": "...base64...",
            "aadhaarNumber": "XXXXXXXX8888", // masked aadhaar number
            "generatedAt": "2024-03-22T15:18:35.269+05:30"
        },
        "xml": {
            "xmlBase64": "...base64..." 
        }
    }
}

#Web redirection flow

status and id will be passed as query parameters through the redirection callback url

https://{your_redirection_url}?status={status}&id={ekyc_id}&errorCode={code}

#Data Model


eKYC Request Status
ValuesDescription
CREATEDLink created but not used
KYC_REQUESTEDConsent success and KYC request success from NPCI
SUCCESSReceived KYC data
ERRORAny internal errors

#Error Codes


Error codesDescription
internal_server_errorAn internal server error has occurred, please try again in some time. OR Upstream service error
unauthorizedUnauthorized request
invalid_requestInvalid request body
not_foundThe resource you are looking for was not found
too_many_requestsRequest made too soon. Please retry after some time.

Was this page helpful?