Offline Aadhaar KYC, also known as OKYC, adheres to UIDAI guidelines,
ensuring legal compliance in the KYC process. Customers can furnish their
Aadhaar number and authenticate it through an OTP sent to their
Aadhaar-linked mobile number. This authentication grants them access to a
downloadable XML file containing comprehensive Aadhaar details, including
name, gender, date of birth, and address.
By default, this file is securely locked. To access its contents, customers
establish a 4-digit access code, providing an additional layer of security
and control over their Aadhaar information.
Utilize our OKYC APIs to instantly retrieve Aadhaar XML for your users within
your app or website, ensuring full privacy compliance. We provide
user-friendly screens, readily deployable for your customers to obtain their
Aadhaar XML in a shareable format and set up a share code. This share code
grants you access to the file's contents.
Offer your customers a smooth experience for OKYC. Extract verified details
of your customers with confidence.
Whichever industry you belong to—insurance, finance, gaming, or even
transportation and logistics—you can ease the onboarding and verification
processes for your customers.
Once (Website Name)'s Sales team has interacted with you and confirmed
integration, this process will begin. You will need to add a few KYC details
and review some agreements.
(Website Name) can provide x-client-id,
x-client-secret and x-product-instance-id. These
credentials are required to make API calls on Sandbox or Prodution.
Simply redirect your customer to pre-built screens with carefully
designed UX, and collect Aadhaar details. Theme screens to match
your brand. Look at the pre-built
screens guide to proceed.
(website name)’s web based solution can be used to complete a customer’s KYC with
offline Aadhaar—within your own app or website, in real-time. Offline
Aadhaar involves getting a downloadable, locked XML file with Aadhaar
information from your customers.
Essentially, only 2 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.
Post this, the customer should be redirected to (website name)’s UI for
collection of details like Aadhaar number and share code for the
locked XML file.
Get OKYC request status—Get status of customer
verification by providing the request id.
Additionally, here are the URLs you would need for these APIs—
Sandbox—https://dg-sandbox.(website name).co
Production—https://dg.(website name).co
Headers—Contact (website name) for providing the credentials required to
successfully call (website name) APIs. This contains:
Call this API to create a unique request to get your customer started on the
OKYC journey.
(website name)’s pre-built screens will handle the OKYC completion flow, but you need
to give (website name) a redirectURL—this is where we will redirect your
customer, once the OKYC journey is complete. This is the only param needed
to create a new OKYC request.
Your request has a valid redirectURL and (website name)
has processed your request successfully.
The button shown in the
screen should have response.url as the
link.
Request
Share a redirectURL to send your customers to,
after the OKYC journey is completed by your customer, on
(website name) screens.
You will get a unique URL from (website name)—OKYC details
will be collected here—where you will have to redirect your
customer.
{
"id":"7097e53a-ba29-48a2-983d-878433b4f33e",//unique request id for the OKYC request
"url":"https://dg-sandbox.(website name).co/okyc/initiate/uuid",//this is where you will redirect your customers
"validUpto":"Wed, 23 Jun 2021 19:33:55 GMT",//the time till when the request id is valid
"status":"incomplete"//status against the request id
}
url is a (website name) generated URL, that is unique to a
particular request id. This is where you should
redirect the customer to, to complete their KYC. You can
generate a new url as many times as you want without
additional charges.
are used to collect OKYC details from your customer.
The following details are collected, as shown in the sample screen flow
below—
Aadhaar number —not saved/stored by (website name)—which is used
to fetch the corresponding XML file for the customer, after an
OTP verification is done with Aadhaar linked mobile number.
Share code is a 4 digit pin set by the customer and
serves as the password to unlock the contents of the XML file.
The screen on the left shows (website name)’s UI. This is what your customers
see when filling in details to complete their OKYC.
When OKYC is completed, (website name) will
redirect the customer to the redirectURL that you
provided in the Create OKYC request API. (website name) will append the
share code provided by the customer, and the request
id to the provided URL. You should store both these
values on your system to access the XML file at a later stage.
Call this API to view status of an OKYC journey that you initiated with a
customer.
You can call this API whenever you need to
check for the status associated with a particular request
id.
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.
Your request has a valid OKYC
request id and 4-digit shareCode.
Request
GET /api/okyc/:requestId/:shareCode/
Response
When status is complete, you will
get all customer KYC details included in the XML, and the
URL for the zip file.
(website name)’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
(website name). 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 (website name). 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.(website name).co
Production URL—https://dg.(website name).co
Headers—Contact (website name) for providing the credentials required to
successfully call (website name) APIs. This contains:
Call this API to initiate your customer’s OKYC journey. Pass the previously
shared request id in the API call.
Your request has been processed successfully.
Request
GET /api/okyc/:requestId/initiate/
Response
As part of the response, you will receive a
captchaImage that is base-64
encoded. This image data is passed on to you by (website name), after
we receive it from UIDAI. You would need to convert this to
an image and display it on subsequent screens to let your
customer enter text from the captcha.
{
"captchaImage":"base 64 Image data",
"id":"7097e53a-ba29-48a2-983d-878433b4f33e",
"captchaRetriesRemaining":4
}
captchaRetriesRemaining indicates the number of
times you can call this API with the same request
id to generate a new captcha.
Call this API once you have collected the following details from your
customer—
aadhaarNumber —This is not saved/stored by (website name), 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
(website name), 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.
For testing this API on Sandbox, use
999999990019 as the Aadhaar number for success and 773032249986 for an
Aadhaar that does not have a linked mobile number. Any other value for
Aadhaar will be considered invalid. Use 2GAD0 for valid captcha and any
other value for invalid.
The request has a valid OKYC request
id and correct captchaCode. Your
customer has successfully received an OTP.
Request
POST /api/okyc/:requestId/verify/
{
"aadhaarNumber":"aadhaarNumber",
"captchaCode":"captchaCode"
}
Response
{
"code":"otp_sent",
"message":"OTP sent to your registered mobile number."
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 (website name), but is
passed on to UIDAI to verify OTP.
Before calling the API, you may want to save
the shareCode on your end, as (website name) will not store it and
will simply pass on the value you provide to UIDAI.
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.
Note that the error description will always
be “Invalid OTP”. We are working on more appropriate descriptions, and
will release them soon.
Your request has a valid OKYC request id and
correct otp as per UIDAI. Additionally, it has
the correct shareCode that was previously set by your
customer.
In the event that the
otp is incorrect, you would need to
redirect your customer to the screen you use to collect
OTP. Your customer can retry entering the same OTP up to
3 times.
You may also let your
customer receive a new OTP by calling the Verify
OKYC request API again. The old OTP will be
void after new OTP is generated. Captcha, since already
verified, will be honoured still and you needn’t fetch a
fresh captcha from (website name) to display to your customer.
Request
If you pass the correct value of the shareCode
to (website name), and if the status of the OKYC request
is complete, (website name) will respond with details
from your customer’s Aadhaar XML file.
POST /api/okyc/:requestId/complete/
{
"otp":"132347",
"shareCode":"1234",
"aadhaarNumber":"999999990019"
}
Response
If the value of the shareCode is incorrect, the
status associated with this OKYC request
id will remain in incomplete
state. Please retry the API to move the status
to complete.
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.
If the request status is
incomplete, call the Complete OKYC request
API with a correct otp input to mark request
status as complete.
You can call this API whenever you need to
check for the status associated with a particular request
id.
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.
Your request has a valid OKYC
request id and 4-digit shareCode.
Request
GET /api/okyc/:requestId/:shareCode/
Response
When status is complete, you will
get all customer KYC details included in the XML, and the
URL for the zip file.
The following guide describes the redundancy implementation of our Aadhaar
OKYC APIs. Due to intermittent issues on our supply partner's end, we have
introduced an Aadhaar Redundancy API, which uses either supply partner to
perform Aadhaar Verification and fetch a user's Aadhaar details, depending
on uptimes. You will need the following 2 APIs—
Create Aadhaar Verification Request—This lets you
initiate a verification request.
GET Aadhaar Verification Details—This lets you check
the status associated with the verification request, and if complete,
fetch the verification details.
Here are the URLs you would need for this integration—
Sandbox—https://dg-sandbox.(website name).co
Production—https://dg.(website name).co
Headers—Contact (website name) for providing the credentials required to
successfully call (website name) APIs. This contains:
Call this API to initiate Aadhaar Verification for your end customer. A quick
explanation of the request params—
redirectUrl Endpoint to which your end customer will be
redirected to, post completion of verification flow.
Your Aadhaar Verification request was created successfully
Request
POST /api/aadhaar/verify
{
"redirectUrl":"https://(website name).co"
}
Response
You get an id associated with the Aadhaar
verification request, which you can use to check
verification status in the Get Aadhaar Verification
Details API.
Onboard with Aadhaar XML on your platform, in compliance with UIDAI & RBI
guidelines. Simply create a request and share the request URL with your
customers.
