#API integration

Setu’s API solution can be used to complete a customer’s KYC with offline Aadhaar in real-time—with your own screens on your app or website. With this, you will get a downloadable, locked XML file with Aadhaar information from your customers.

The following APIs are required for enabling this flow—

• Create OKYC request—Create OKYC request for your customer. You will get a unique id in the response which can be used to track this particular request.
• Initiate OKYC Request—Initialise the OKYC request for your customer with the previously returned request id and receive a base64 encoded captchaImage from Setu. Once you have called this API, you can redirect your customer to your OKYC screens, to collect Aadhaar number and captcha from your customer.
• Verify OKYC Request—Share the aadhaarNumber and captchaCode, collected from your customer, with Setu. Next, redirect your customer to a screen to collect OTP sent to your customer’s Aadhaar linked mobile number. Also request your customer to enter a 4 digit share code—this is the code that will be used to unlock you customer’s fetch Aadhaar XML file.
• Complete OKYC Request—Share the collected otp and shareCode to complete verification process. Next, you can call the Get OKYC request status API. Once the OKYC request has been processed successfully you wll get customer details from the Aadhaar and the XML file link in the response.
• Get OKYC request status—Get status of customer verification by providing the request id and optionally, the shareCode.

Additionally, 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 Setu for providing the credentials required to successfully call Setu APIs. This contains:
  • x-client-id
  • x-client-secret
  • x-product-instance-id

#Create OKYC request

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

POST /api/okyc/ 

{  
  "id": "7097e53a-ba29-48a2-983d-878433b4f33e", 
  "validUpto": "Wed, 23 Jun 2021 19:33:55 GMT", 
  "status": "incomplete" 
}  

#Initiate OKYC request

Call this API to initiate your customer’s OKYC journey. Pass the previously shared request id in the API call.

GET /api/okyc/:requestId/initiate/ 

{  
   "captchaImage": "base 64 Image data", 
   "id": "7097e53a-ba29-48a2-983d-878433b4f33e", 
   "captchaRetriesRemaining": 4 
}  

#Verify OKYC request

Call this API once you have collected the following details from your customer—

• aadhaarNumber —This is not saved/stored by Setu, but is passed on to UIDAI to initiate sending an OTP to your customer’s Aadhaar linked mobile number.
• captchaCode—An encoded captcha image is provided to you by Setu, as received from UIDAI, in the Initiate OKYC request API response. You would need to convert this to an image and display it to your customer, wherein they would enter the text associated with the captcha. A correct captcha response is expected to proceed to the next API call.

POST /api/okyc/:requestId/verify/ 
 
{  
   "aadhaarNumber": "aadhaarNumber", 
   "captchaCode": "captchaCode" 
}  

{ 
    "code": "otp_sent", 
    "message": "OTP sent to your registered mobile number." 
} 

#Complete OKYC request

Call this API once you have collected the following details from your customer—

• otp —This should be filled in by the customer, who would have received an OTP from UIDAI, on their Aadhaar linked mobile number.
• shareCode is a 4 digit pin set by the customer and serves as the password to unlock the contents of the XML file at a later stage.
• aadhaarNumber —This is not saved/stored by Setu, but is passed on to UIDAI to verify OTP.

This API returns the unwrapped Aadhaar response, as well as a link to the XML, if the otp is correct. If otp is incorrect, the OKYC status remains incomplete. To test for different scenarios, use the following otp values on Sandbox—

• Use 123456 for a valid OTP.
• Use 123457 for OTP to mimic 1st failed attempt.
• Use 123458 for OTP to mimic 2nd failed attempt.
• Use 123459 for OTP to mimic failed attempts limit exceeded.
• Anything aside from these values returns an error description as a generic “error”, if the upstream service returns an error.

You may use any 4 digit value for the shareCode, when testing on Sandbox.

POST /api/okyc/:requestId/complete/ 
 
{  
   "otp": "132347", 
   "shareCode": "1234",
   "aadhaarNumber": "999999990019"
}  
 

{ 
  "aadhaar": { 
    "address": { 
      "careOf": "S/O: Gurjar Pradeep", 
      "country": "India", 
      "district": "Bangalore", 
      "house": "# 90 1 Cross", 
      "landmark": "Near Talkies", 
      "locality": "Nagarabhavi", 
      "pin": "560072", 
      "postOffice": "Nagarbhavi", 
      "state": "Karnataka", 
      "street": "Nagarbhavi 1st Main Road", 
      "subDistrict": "Bangalore North", 
      "vtc": "Bangalore North" 
    }, 
    "dateOfBirth": "23-05-1990", 
    "email": "550fa5fd91eee3f29f6361a8c89aa9713d4d38811d1a5", 
    "gender": "M", 
    "generatedAt": "20210419145604802", 
    "maskedNumber": "xxxx-xxxx-8832", 
    "name": "Jignesh Gurjar", 
    "phone": "09c91184c1d610282d661dd63d257e3b44446853fb1388c9d5b", 
    "photo": "/9j/4AAQSkZJRgABAgAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKD==", 
    "userProfile": {
      "unmaskedEmail": "abc@def.com",
      "unmaskedPhone": "9999999999"
    },
    "verified": { 
      "email": false, 
      "phone": false, 
      "signature": true 
    }, 
    "xml": { 
      "fileUrl": "https://setus3linkgoeshere.com/", 
      "validUntil": "Wed, 23 Jun 2021 19:33:55 GMT", 
      "shareCode": "1234" 
    } 
  }, 
  "status": "complete", 
  "id": "7097e53a-ba29-48a2-983d-878433b4f33e" 
} 

#Get OKYC request status

Call this API to view status of an OKYC journey that you initiated with a customer.

When the status of the OKYC request id is complete, this API returns—

• Aadhaar details in json, if a correct shareCode is passed.
• An error, if an incorrect shareCode is passed.
• A link to the zip/xml aadhaar details, if no shareCode is passed.

Possible values for status, received as part of the response—

• When complete, KYC is complete for a customer. If you provide a shareCode in the API request, you will get all customer details from the Aadhaar XML file.
• When incomplete, you can check for KYC completion after some time.
• In case the request has expired, your will get a 404 error code.

GET /api/okyc/:requestId/:shareCode/ 

{ 
  "aadhaar": { 
        "address": { 
              "careOf": "S/O: Gurjar Pradeep", 
              "country": "India", 
              "district": "Bangalore", 
              "house": "# 90 1 Cross", 
              "landmark": "Near Talkies", 
              "locality": "Nagarabhavi", 
              "pin": "560072", 
              "postOffice": "Nagarbhavi", 
              "state": "Karnataka", 
              "street": "Nagarbhavi 1st Main Road", 
              "subDistrict": "Bangalore North", 
              "vtc": "Bangalore North" 
        }, 
        "dateOfBirth": "23-05-1990", 
        "email": "550fa5fd91eee3f29f6361a8c89aa9713d4d38811d1a5", 
        "gender": "M", 
        "generatedAt": "20210419145604802", 
        "maskedNumber": "xxxx-xxxx-8832", 
        "name": "Jignesh Gurjar", 
        "phone": "09c91184c1d610282d661dd63d257e3b44446853fb1388c9d5b", 
        "photo": "/9j/4AAQSkZJRgABAgAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKD==", 
        "userProfile": {
          "unmaskedEmail": "abc@def.com",
          "unmaskedPhone": "9999999999"
        },
        "verified": { 
              "email": false, 
              "phone": false, 
              "signature": true 
        }, 
        "xml": { 
            "fileUrl": "https://dg-esign-uat.s3.amazonaws.com/testFolder/sample.zip", 
            "shareCode": "1111", 
            "validUntil": "Tue, 27 Jul 2021 12:16:27 GMT" 
       }  
      }, 
      "status": "complete", 
      "id": "7097e53a-ba29-48a2-983d-878433b4f33e" 
}