Setu
eKYC

Quickstart

API Playground

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.

201

SUCCESS 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"
}

400

BAD REQUEST Your request body has field redirection_url missing.

Request
POST /api/ekyc/
            
{
  "webhook_url": "<client_webhook_url>" // Optional
  "redirection_url": "<client_redirection_url>"
}
Response
{
    "errorCode": "invalid_request",
    "errorMsg": "1 validation error(s): [1] body -> redirectionUrl: Field required"
}

500

INTERNAL SERVER ERROR Setu has failed to process your request due to some error in code or an unreachable database; or because authentication services are down.

Request
POST /api/ekyc/
            
{
  "webhook_url": "<client_webhook_url>" // Optional
  "redirection_url": "<client_redirection_url>"
}
Response
{
    "errorCode": "internal_server_error", // or upstream_service_error
    "errorMsg": "An internal server error has occurred"
}

Get eKYC request

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

200

Response Type 1

Response Type 2

404

NOT FOUND When the provided request_id is incorrect or deleted.

Request
GET /api/ekyc/:request_id
Response
{  
    "errorCode": "not_found",
    "errorMsg": "eKYC id not found"  
}

500

INTERNAL SERVER ERROR Setu has failed to process your request due to some error in code or an unreachable database; or because authentication services are down.

Request
GET /api/ekyc/:request_id
Response
{
    "errorCode": "internal_server_error", // or upstream_service_error
    "errorMsg": "An internal server error has occurred"
}

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_error

An 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.

On this page

OverviewCreate eKYC request201400500Get eKYC request200404500Webhook responseWeb redirection flowData ModelError Codes