Cross Device Facial Image Capture Journey

This page covers the Facial Image capture journey initiated from a portal

1.1 Capture Request

In case of the cross-device CAPTURE flow, the verifier has to render a JWT token as a QR in the browser. JWT to contain follwoing attributes in the payload section.

{
    "txn": "94f63917-708a-4e58-9001-fce56d839948",
    "i": "CAPTURE",
    "pidVer": "1.0",
    "otp": ""<otp for MFA>,
    "wadh="<refer to kyc api>"
    "cb": "https://myaadhaarstage.uidai.gov.in/v1/esignet/authorization/publishBioAuth/2.5",
    "aud": "https://myaadhaarstage.uidai.gov.in",
    "iss": "https://myaadhaarstage.uidai.gov.in/v1/esignet",
    "exp": exp,
    "iat": iat,
    "ht": "Name of the person",
    "jti": "8a9d7c2b-b932-4131-9e36-43f22a019be5"
}

JWT Header Structure

{
  "alg": "ES256",
  "typ": "capture-req+jwt",
  "kid": "did:myaadhaarstage.uidai.gov.in:123#1"
}

1.2 Request Params

Element	M/O	Type	Description
txn	M	String	A unique transaction ID that serves as a nonce to prevent replay attacks. It ensures that each request is unique, and the same request cannot be processed multiple times.
i	M	String	Indicates the action to be performed by the aadhaar app. For the capture request, the value would be CAPTURE
pidVer	M	String	Version of the pidBlock
otp	O	String	OTP for Multio factor authentication
wadh	O	String	wadh fro eKYC flow. Not implemented as of now.
cb	M	String	The callback URL where the pid response will be sent after the transaction is processed.
lang	O	String	This filed provides hint to the aadhaar app 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)
aud	M	String	The audience claim indicates the intended recipient of the pid request or the Authorization Server.
iss	M	String	The issuer claim identifies the Authorization Server or the entity issuing the request. In this case, it specifies the e-signature service endpoint of UIDAI.
exp	M	String	The expiration time of the request, specified as a Unix timestamp (in seconds). This ensures that the request is valid only for a certain period of time. After the expiration time, the request is no longer valid.
iat	M	String	The issued at claim indicates the time at which the request was created, also in Unix timestamp format.
ht	O	String	Hint to trigger the selction of the profile from the aadhaar app. This has to be name of the person.
jti	M	String	The JWT ID (jti) is a unique identifier for the token. It helps to uniquely identify the request and prevent replay attacks (i.e., the same request being submitted multiple times).

Allowed alg Values for JWT

alg Value	Algorithm
RS256	RSA with SHA-256
ES256	ECDSA with P-256

1.3 Capture Response

In response the cross device CAPTURE request, aadhaar app would send the response to the callback (cb) URL the PID Response as part of a POST call.

POST /submit-pid HTTP/1.1
Host: example.com
Content-Type: application/xml

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

Content-Type would be set to application/xml for the POST response.

1.4. Capture 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.