App Initiated Capture Journey

This page covers Capture Intent Specifications

This section covers Facial image capture flow. Currently Facial image capture for Authenticatiomn is supported by the FaceRd app, which will be parralley supported in the aadhaar app.

1.1 App Initiated Capture Journey

The app-initiated journey enables an AUA (Authentication User Agency) application to securely capture a live facial image from the ANH's device. This captured image is converted into a signed and encrypted PID (Personal Identity Data) block, which can then be used to perform Aadhaar Face Authentication.

The capture intent request may include optional elements such as:

• otp: Enables the AUA app to perform Face + OTP-based authentication, enhancing security by combining biometric and possession factors.

• wadh: Allows the captured face data to be used for eKYC API calls, in accordance with the Aadhaar authentication framework.

Note: This feature is only available for the AUA apps. OVSE apps will get error messages for CAPTURE Intent call.

1.2 Journey

The following visuals cover the Experience for an app-to-app Capture Intent

1.2.1 API Contract

Intent action : "in.gov.uidai.rdservice.face.CAPTURE"
Intent request payload key : "request"
Intent request payload value : "pid options"

1.2.2 Invocation

context.startActivityForResult(intent, request-code);

Notes:

1. Activities of aadhaar app should be started using startActivityForResult() expecting result in onActivityResult for given request-code.

2. Please refer to the sample reference project for any help in integrating with the headless apps.

3. UIDAI recommends to support multiple language feature to enable users to select preferred laugange to follow the instructions. This option should be enabled in AUA app context.

4. AUA should handle error codes/message with right feedback messages to enhance the user experience. Aadhaar app messages are designed to provide actional messages that are applicable to both end users of app and backend development/support teams. Below categorization of error codes should help:

  a. 1xx, 2xx are usually integration time error codes
  b. 7xx are end user usage related information messages. End users should be guided appropriately.
  c. 8xx error codes are related to device. End users should be guided appropriately to take corrective measures.
  d. 9xx error codes are related to network.
  e. 97xx, 98xx and 99xx are related to aadhaar/RD app.

1.2.3 Request

<?xml version="1.0" encoding="UTF-8"?>
<PidOptions ver="1.0" env="P">
    <Opts format=0 pidVer="1.0" otp="" wadh="<refer to kyc api>" />
    <CustOpts>
        <Param name="txn" value="<unique uuid>"/>
	    <Param name="lang" value="<string>" minOccurs=0/>
        <Param name="ht" value="<string>" minOccurs=0/>
    </CustOpts>
	<BioData />
</PidOptions>

1.2.4 Request Params

Element	M/O	Type	Description
pidOption	M	String	Refer to RD specification section 2.6.2. ver, env are mandatory attributes.
pidOption:opts	M	String	Refer to specification section 2.6.2. format (0=XML, 1=PROTOBUF), pidVer are mandatory attributes. PROTOBUF is currently not supported. otp and wadh are optional.
pidOptions:custOpts:txn	M	String	name: txn value: new UUID to correlate between Capture intent call. This txn CAN BE be same as AUA’s auth xml txn Id.
pidOptions:custOpts:lang	O	String	name: “lang” value: new string to correlate between Capture intent call. This language will be used to change app language as per input (en:English, hi:Hindi, bn:Bengali, mr:marathi, kn:Kannada, ml:Malayalam, or:Oriya, ta:Tamil, te:Telugu)
pidOptions:custOpts:ht	O	String	Ht is used to share the hint with the aadhaar app to trigger selection of the correct profile. If the hint fails to match any of the profile, all the profiles woudl be shown for the selection by the ANH
BioData	O	String	Currently not supported. Holds list of PidData elements obtained from Finger or Iris RD Services. This feature enables Fusion Authentication between Face and other biometric modalities.

M - Mandatory fields, O - Optional fields

1.2.5 Response

<PidData>
    <Resp errCode="" errInfo="" fCount="" fType="" iCount="" iType="" 
          pCount="" pType="" nmPoints="" qScore=""/>
    <DeviceInfo rdsId="" rdsVer="" dpId="" dc="" mi="" mc="" />
    <Skey ci="">encrypted and encoded session key</Skey>
    <Hmac>SHA-256 Hash of Pid block, encrypted and then encoded</Hmac>
    <Data type="X|P"> base-64 encoded encrypted pid block </Data>
    <CustOpts>
        <Param name="txn" value="<txnId from the request>" />
        <Param name="txnStatus" value="PID_CREATED" />
    	<Param name="responseCode" value=""/>
    </CustOpts>
</PidData>

1.2.6 Response Params

Element	M/O	Type	Description
pidOption	M	String	Refer to RD specification section 2.6.2.
pidOptions:custOpts	M	String	Param name: “txnId” value: uuid passed in the request.
pidOptions:custOpts	M	String	Param name: “txnSstatus” value: "PID_CREATED".
pidOptions:custOpts	O	String	Param name: “responseCode” value: "uuid received from facerd app".
DeviceInfo	M	String	Device details as per RD specification section 2.6.2. This is used in AUA app to create AUTH xml request.
Skey	M	String	Encrypted (PKI) AES key used to encrypt the PID. This is used in AUA app to create AUTH xml request.
Hmac	M	String	Hash of Pid block, encrypted and then base4 encoded. This is used in AUA app to create AUTH xml request.
Data	M	String	base64 encoded encrypted pid block. THis is used in AUA app to create AUTH xml request.

M - Mandatory fields (when request is processes successfully), O - Optional fields