Aadhaar SDK UIDAI

Aadhaar SDK provides the user to verify Aadhaar status and get relevant information from UIDAI.

Find steps below to integrate the Application SDK

  1. Aadhaar SDK has to be integrated with mobile application.
  2. In the integration UserId and CredentialId are mandatory fields for integration. CredentialId is unique and provided by Bureau.
  3. UserId is a unique id that is generated per user and can be either the phone number/email/UUID etc that is used to represent every unique user.

Aadhaar Flow

  • User is guided to the UIDAI website to download the paperless e-KYC (Aadhaar .xml) Inputs for "Aadhaar Number" & Captcha are filled by the end user. Both the details will be validated by UIDAI on the screen and in case of validation error the message will be displayed accordingly on the screen.
  • On continuing, An OTP is received by the end user which is then auto read by the SDK.
  • Once the details entered are authenticated, the Aadhaar .xml is downloaded in a .zip which is password(share code) protected

Minimum Requirements

  • minSdkVersion 21
  • AndroidX

Integrations Guide

Add following lines in your root build.gradle

allprojects {
    repositories {
        ...
        maven { url "https://jitpack.io" }
    }
}

Add following lines in your module level build.gradle

android {
    ...
    compileOptions {
       sourceCompatibility = 1.8
       targetCompatibility = 1.8
    }
}
dependencies {
    ....
       implementation 'com.github.Bureau-Inc:android-aadhaar-all-in-one-sdk:x.x.x'
}

Latest version - 0.72.0

Initialise SDK

PrismEntryPoint prism;
        
        yourinitbutton.setOnClickListener(new View.OnClickListener() {
            @Override
            public void onClick(View v) {
            
            //instantiate your prism 
            prism = PrismInstanceProvider.getInstance(context,activity);
            
            //Initialize your prism only once
               prism.initialize(your credentialId,your user id,
                new PrismCallBack(){

                    override fun onKYCFinished(
   								  aadhaarData: ClientAadhaarData?,
    								methodName: String?,
   								  isSuccess: Boolean?, errorType: String	
										) {
    								//log your aadhaar data or error type

										}

										override fun eventCalled(eventName: String) {
   									//log your event here
    
										}

										override fun onTryAgainShown(
    								numberOfRetriesLeft: Int,
    								retryCallback: RetryCallback
										) {
   
        						retryCallback.onStopSDK() //To stop SDK(Note: You need only call beginkycflow again and not initialize)
                    //or
        						retryCallback.onContinue()//To continue show the sdk try again error screen
									}

                }
               ,a boolean to indicate whether flow should be run on production configuration,an integer to indicate number of retries for try again screen,PrismCustomisation.Builder().build());
               //You can Add customisation to SDK's UI by adding values to PrismCustomisation Builder

                
            //Adding config to specify the new Aadhaar Flow
                prism.addConfig(new Config(myAadhaarUidaiFlow));
                
               
                
           //KYC initiate call
           prism.beginKYCFLow();
            }
        });

In your fragment's/activity's onDestroy function, call
prims.resetPrismSDKConfig()

To set number of retries and custom error messages.

var errorMap = HashMap<String,String>(

errorMap.put(ERROR_MESSAGE_FOR_OTP_GENERATION,"Your custom error")
errorMap.put(ERROR_MESSAGE_FOR_OTP_SUBMISSION,"Your custom error")

prism.initialize(
                    merchantId,
                    userId,
                    object : PrismCallBack {
                        override fun onKYCFinished(
                            aadhaarData: ClientAadhaarData?,
                            methodName: String?,
                            isSuccess: Boolean?, errorType: String
                        ) {
                           

                        }

                        override fun eventCalled(eventName: String) {
                          
                        }

                    },

                    isProduction,//Boolean to indicate if SDK is to be used in production
                    prismCustomisation = PrismCustomisation.Builder().toolBarTitle("YOUR_TITLE").hideToolbar(false).setLogoDrawable(R.drawable.your_logo).mainPageTitle("<Your Aadhaar Entry title>").otpPageTitle("<Your OTP Title>").build(),
                    numberOfRetries = n,errorMap )//n is an integer to indicate the number of retries, if this is not required this can be set to 0

Notes

  1. Please call the above function only on onDestroy of the fragment where instanceProvider and initialize has been called.
  2. This call is optional and forces sdk cache to clear. Call only when retention of old sdk config is maintained.
  3. Once the call is invoked it clears all config so make sure you call instanceProvider and initialize again when starting a new flow.
  4. prism.beginKYCFlow can be called multiple times in between initialize and resetPrismSDKConfig

Callback

When Aadhaar fetch is successful the callback returns the isSuccess boolean as true and when a failure happens the callback returns the isSuccess boolean as false.

new PrismCallBack(){

                    @Override
                    public void onKYCFinished(ClientAadhaarData aadhaarData, String methodName, Boolean isSuccess,String errorType) {
                               if(isSuccess)
                               {
                                    //Write your success logic here
                                    //the object aadhaar data contains the details
                                    //errorType will be empty here
                                    
                                    Log.d("Aadhaar Data", aadhaarData.getJsonString.ToString());
                                    Log.d("XML File Uri", aadhaarData.getXmlFileUri().toString());
                                    Log.d("Aadhaar Data", aadhaarData.getZipFileUri().toString());
                                    Log.d("Aadhaar Data", aadhaarData.getShareCode.toString());
                                    
                               }
                               else
                               {     //Check errorType here
                                      if(errorType== ENDPOINTS_DOWN)
                                        Log.w("Aadhaar Error","No endpoints Available")
                                      else if(errorType== INVOID_AUTH_ERROR)
                                        Log.w("Aadhaar Error","Not authorized")
                                      else if(errorType== UIDAI_ERROR)
                                        Log.w("Aadhaar Error","UIDAI Site Error")
                                      else if(errorType== INTERNET_ERROR)
                                        Log.w("Aadhaar Error","Intenet Error")
                                      else if(errorType== SDK_ERROR)
                                        Log.w("Aadhaar Error","SDK Error")
                                      else if(errorType== USER_CANCELLED)
                                         Log.w("Aadhaar Error","Cancelled by user")
                                         
                                         
                            
                                     //Write your failure logic here
                                     //You can retry the method by calling beginKYCFlow() again as shown below
                                   prism.beginKYCFLow();
                               }
                    }
                }

Notes

  1. UserId and MerchantId are mandatory fields and should not be empty. UserId is a unique string that represents each unique user trying the flow.
  2. UserTracking
    UserId can be used to call Bureau backend API to fetch data regarding user. It should be unique string in nature. For each KYC flow the userId should be uniquely generated. It can be mobile number or any email associated to a user also.
  3. Response returned from the SDK
    • xml file uri
    • zip file uri
    • share code to open zip file
    • processedJSON
    • The PrismCallBack added in the initialize function return's whether we have successfully fetched details or not

SDK Callbacks

These are event callbacks that can be used to get user details.

DescriptionSDK Code
AADHAAR_ENTRY_SCREENAadhaar Entry Screen
OTP_ENTRY_SCREENOTP Entry Screen
PROGRESS_SCREENLoading Screen
WARNING_SCREENTry Again Screen
SUCCESS_SCREENSuccess Screen

SDK Errors

SDK CodeDescription
UIDAI_ERRORUIDAI services are down
INVOID_AUTH_ERRORNot authorised
INTERNET_ERRORNetwork error
USER_CANCELLEDUser cancelled
SDK_ERRORBureau SDK error
ENDPOINTS_DOWNAll endpoints are down
MOBILE_NOT_LINKEDAadhaar number does not have mobile number
FORCE_STOP_FROM_PARENT_APPThe sdk process has been terminated by the parent app
UIDAI_VERIFICATION_FAILEDFailure in obtaining XML file after successful submission of the OTP

Serverside Base URL's

Server side code to get the details

curl --location --request GET 'https://api.overwatch.stg.bureau.id/v1/id/<UserId>/suppliers/offline-aadhaar' \
--header 'Authorization: Basic AuthHeader'
curl --location --request GET 'https://api.overwatch.bureau.id/v1/id/<UserId>/suppliers/offline-aadhaar' \
--header 'Authorization: Basic AuthHeader'

Response

{
    "aadhaarXMLUrl": "https://xxx-prd-mb-xxx-documents-/91feeafe-1111-1111-1111-8e9fe0400920.xml?",
    "city": "User City",
    "district": "User District",
    "dob": "DD-MM-YYYY",
    "gender": "M",
    "merchantId": "auth0|61d11111114e7021",
    "name": "User Name",
    "pincode": "pin code",
    "requestId": "57e7b43d-1111-4e4c-1111-a096e7400a5f",
    "state": "Karnataka",
    "statusCode": 200,
    "street": "addresss",
    "timestamp": 1674201457708
}
{
  "errors": {
    "code": 400,
    "description": "Request contains an invalid param in request body which does not exist",
    "message": "BAD_REQUEST",
    "metadata": " ",
    "referenceId": "b090f2a1-ebf4-4fdc-bcdc-296cfc7e4ea1",
    "type": "BAD_REQUEST"
  },
  "merchantId": "auth0|61df1111107111021",
  "requestId": "d46ff15d-1111-4568-1111-b21bbdd3962f",
  "statusCode": 400,
  "timestamp": 1657794502770
}
{
  "errors": {
    "code": 422,
    "description": " ",
    "message": "NO_RECORD_FOUND",
    "metadata": " ",
    "referenceId": "b090f2a1-ebf4-4fdc-bcdc-296cfc7e4ea1",
    "type": "NO_RECORD_FOUND"
  },
  "merchantId": "auth0|61df1111107111021",
  "requestId": "d46ff15d-1111-4568-1111-b21bbdd3962f",
  "statusCode": 422,
  "timestamp": 1657794502770
}
{
  "errors": {
    "code": 503,
    "description": " ",a
    "message": "INTERNAL_SERVICE_UNAVAILABLE",
    "metadata": " ",
    "referenceId": "b090f2a1-ebf4-4fdc-bcdc-296cfc7e4ea1",
    "type": ""
  },
  "merchantId": "auth0|61df1111107111021",
  "requestId": "d46ff15d-1111-4568-1111-b21bbdd3962f",
  "statusCode": 503,
  "timestamp": 1657794502770
}

SDK Customisations

To customise the theme of the activity use the following theme in your styles.xml file.
Error message show to the user can be customised by defining following strings in your strings.xml file

<style name="PrismAppTheme">
    ...
    <!--Add Theme Customisation here-->
</style>
<!--To add customisation to toolbar in SDK's activity add the following style-->
<style name="PrismToolbarTheme" parent="ThemeOverlay.AppCompat.Dark.ActionBar" >
    <item name="android:background">@drawable/invoid_button_bg</item>
</style>
<!--To add customisation to buttons in SDK add the following style-->
<style name="PrismButtonTheme" parent="@android:style/Widget.Button">
    <item name="android:textColor">@android:color/white</item>
    <item name="android:shadowColor">#FF000000</item>
    <item name="android:shadowDx">0</item>
    <item name="android:shadowDy">-1</item>
    <item name="android:shadowRadius">0.2</item>
    <item name="android:background">@color/black</item>
    <item name="android:textSize">14sp</item>
    <item name="android:textStyle">bold</item>
</style>
Error message show to the user can be customized by defining following strings in your strings.xml file
<!--Error message shown in case of OfflineAadhaarHelper.UIDAI_ERROR-->
<string name="invoid_uidai_error">Server down, please try after some time</string>
<!--Error message shown in case of OfflineAadhaarHelper.INVOID_AUTH_ERROR-->
<string name="invoid_auth_error">Not authorized</string>
<!--Error message shown in case of OfflineAadhaarHelper.INTERNET_ERROR-->
<string name="invoid_check_internet_error">Please check your internet connection</string>

Code Customisations

PrismCustomisation.Builder().toolBarTitle("YOUR_TITLE").hideToolbar(false).setLogoDrawable(R.drawable.your_logo).mainPageTitle("<Your Aadhaar Entry title>").otpPageTitle("<Your OTP Title>").build()

To customise the color of the button of the SDK UI override the following color in your colors.xml file.

<color name="bureau_button_bg">#FFCA20</color>