0% found this document useful (0 votes)
15 views7 pages

SubAUA Portal Application - Web Based Integration Document V1.1.

The document outlines the technical integration requirements for the SubAUA Portal application developed by Protean eGov Technologies Limited, detailing the process for e-KYC and Aadhaar authentication services. It includes prerequisites such as signing and encryption certificates, request and response formats, and mandatory input parameters for successful integration. Additionally, it provides error codes and a sample request XML for reference.

Uploaded by

techproindia2017
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as DOCX, PDF, TXT or read online on Scribd
0% found this document useful (0 votes)
15 views7 pages

SubAUA Portal Application - Web Based Integration Document V1.1.

The document outlines the technical integration requirements for the SubAUA Portal application developed by Protean eGov Technologies Limited, detailing the process for e-KYC and Aadhaar authentication services. It includes prerequisites such as signing and encryption certificates, request and response formats, and mandatory input parameters for successful integration. Additionally, it provides error codes and a sample request XML for reference.

Uploaded by

techproindia2017
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as DOCX, PDF, TXT or read online on Scribd
You are on page 1/ 7

Technical Integration document for

SubAUA Portal application (Web flow)

By Protean eGov Technologies Limited.

Version 1.1

Release Date: 30-05-2023

Version 1.1 Confidential Page 1 of 7


Revision History

Date Revision No. Description of Change

30-May-23 1.0 First Version

Print format request (pfr=””) attribute added in eXml


25-Jan-24 1.1 for retrieving E-Aadhaar document in PDF format as
part of Ekyc response .

 Introduction.

Version 1.1 Confidential Page 2 of 7


Protean eGov Technologies Limited [Protean] (formerly NSDL e-Governance Infrastructure Limited) has
developed the Web service for authorized entities (referred to as sub-AUA) to avail the e-KYC and Aadhaar
authentication services from portal hosted by Protean. As per UIDAI guidelines, Aadhaar/Virtual ID will be entered
on the portal of Protean (AUA/KUA) by respective Sub-AUA. Sub-AUA will re-direct the client on the portal of
Protean for entering the Aadhaar/Virtual ID to perform e-KYC and Aadhaar authentication. Consent of the
Aadhaar holder has to be obtained on Protean’s portal by clicking the checkbox for consent.

1. Pre-requisites.

 Signing certificate: share the public key of signing certificate for mapping at Protean

 Encryption certificate: share the public key of Encryption certificate for mapping at Protean.

 License key and SubAUA code: License key will be provide by Protean to SubAUA and SubAUA code will
be allotted by UIDAI.

 Purposes: Protean will share the draft of consent and Sub AUA will be required to define the purpose.
Protean will map the consent against the Sub AUA code

 Services: Share the services name required by SubAUA. i.e. Authentication or e-KYC

Guidelines for signing and encryption certificate.

 It should be procured from a valid certification authority as per Indian IT Act


 It should be a class II or class III certificate.
 The certificate should be procured from your Organization name. ‘O’ element should be present in the cer-
tificate under ‘Subject’.
 The Key Usage should be ‘Digital Signature’. It should not be SSL, Server Certificates or any other certifi-
cates.
 For signing purpose, please share the certificate having "key usage" value as "Digital Signature, Non-Re-
pudiation (c0)".
 For encryption purpose, please share the certificate having "key usage" value as "Key Encipherment".

2. SubAUA portal request format:

Version 1.1 Confidential Page 3 of 7


- Pass the request in eXml=” ” parameter and over the HTTPS using POST method.
- Pass the URL encoded request.

<?xml version="1.0" encoding="UTF-8"?><SubAUAReq licenseKey =" " pfr=” ” purpose =" " reqType =" "
returnURL =" " subAuaCode =" " ts =" " txnId =" "><Signature
xmlns="http://www.w3.org/2000/09/xmldsig#">Signature</Signature></SubAUAReq>

3. URL to post the Request:

UAT URL : https://59.163.223.221/SUBAUAWEB/LinkToSubAuaPortal

Production URL : https://ekycservices.egov-nsdl.com/SUBAUAWEB/LinkToSubAuaPortal

4. Mandatory Input Parameter(s) in Request xml :

Sr Attribute Datatype Length Mandatory / Description


No Optional
1 licenseKey VARCHAR 55 M Provided by Protean for authentication
purpose.
2 purpose VARCHAR 3 M . Protean will share the purpose no, which the
Sub AUA is required to pass in request packet.

3 reqType INT 1 M 1. OTP based Ekyc

2. Biometric based Ekyc

3. Biometric based Authentication

4. Demographic based Authentication

5. OTP based Authentication

4 returnURL VARCHAR 100 M Return browser URL of entity

5 subAuaCode VARCHAR 10 M SubAUA code allotted by UIDAI


6 Ts TIMESTAMP 50 M Request time e.g. 2022-05-
30T15:53:49.381+05:30
7 txnId VARCHAR 50 M Use unique alphanumeric transaction ID for
each transaction
8 pfr VARCHAR 1 O For retrieving E-Aadhaar document in PDF
format as part of Ekyc response.

Valid values for this attribute :


Y= E-Aadhaar document in PDF will be return
in Ekyc response.

Version 1.1 Confidential Page 4 of 7


N= E-Aadhaar document in PDF will be not
receive from UIDAI , hence not return in Ekyc
response.
Blank = if pfr= “ “ passed blank, then E-
Aadhaar document in PDF not return in Ekyc
response.
9 Signature M This attribute will contains the signature. The
xml should be signed by using the Sub-AUA‘s
signing certificate

5. Parameter(s) in Response:

 After successfull authentication of SubAUA request xml, user will get redirected on Protean Portal to
perform ekyc and Aadhaar Authentication, as per service opted by SubAUA entity..

 Response will be return to SubAUA provided return URL. Below are the parameters from response.

Sr No Attribute Description
1 Status Based Response status with be : “Y” OR “N” OR “E”.
Y – Successful
N – Unsuccessful
E – Invalid ( Rejected by Protean)
2 transID Initial transaction ID will be displayed
3 kycResXml - In case of Ekyc transaction, this is encrypted and
encoded response.
- In case of Aadhaar authentication , this is encoded
response.

6. Ekyc response xml format .

 SubAUA will be receive the encrypted ekyc xml . This xml is encrypted with the SubAUA encryption
certificate public key.
 Below is the Ekyc response xml format.

<Resp status="" ko="" ret="" code="" txn="" ts="" err="">< kycRes>encrypted and base64 encoded KycRes
element</ kycRes> </Resp>

Resp - container for keeping encrypted e-KYC response. Value of the “Resp” element is base64 encoded
version of the encrypted “KycRes” element.

status - Indicates high level status of the API call. It can have values “0” or “-1”. If the status is “0”, it means
that the encrypted data contained within the “Resp” element is valid. If it contains “-1”, it means the data
should not be decrypted and used.

Version 1.1 Confidential Page 5 of 7


ko – This attribute contains either value “KUA”, “ASA”.

Ret - this is the main KYC API response. It is either “y” or “n”.

code – unique alphanumeric response code for e-KYC API having maximum length 40.

txn – e-KYC API transaction identifier. This is exactly the same value that is sent within the request XML.

ts – Timestamp when the response is generated. This is of type XSD dateTime.

err – Failure error code.

KycRes- It contains encrypted and base64 encoded data packet. This tag i.e. < kycRes> is encrypted with a
dynamic Dec key using AES-256 symmetric algorithm (AES/GCM/NoPadding). Dec key, in turn, is encrypted
with 2048-bit public key of entity using asymmetric algorithm (RSA/ECB/PKCS1Padding).

Once decoded and decrypted, “KycRes” has the following structure and it’s in a plain text:

<KycRes ret="" code="" txn="" ts="" ttl="" actn="" err="">


<Rar>base64 encoded fully valid Auth response XML for resident</Rar>
Version 2.5 Aadhaar e-KYC API
© UIDAI, 2011-2018 http://uidai.gov.in/ Page 12 of 16
<UidData uid="" tkn=””>
<Poi name="" dob="" gender="" />
<Poa co="" house="" street="" lm="" loc="" vtc=""
subdist="" dist="" state="" country="" pc="" po=""/>
<LData lang="" name="" co="" house="" street="" lm="" loc="" vtc=""
subdist="" dist="" state="" country="" pc="" po=""/>
<Pht>base64 encoded JPEG photo of the resident</Pht>
</UidData>
<Signature/>
</KycRes>

7. Protean Error codes list :

Protean error codes and description is attached with this API document. Error codes will also be passed in the
response XML to the Sub AUA for taking suitable action.

8. UIDAI Error codes list :

UIDAI defined error code master is attached. Error codes will also be passed in the response XML to the Sub AUA
for taking suitable action

Version 1.1 Confidential Page 6 of 7


9. Sample request xml :

<?xml version="1.0" encoding="UTF-8"?><SubAUAReq licenseKey="abcdefghijklmn" pfr="Y"


purpose="001" reqType="1" returnURL="https://sample.com/B2BResponseServlet"
subAuaCode="SAMPLE0001" ts="2023-05-11T14:09:03.341+05:30"
txnId="SAMPLE0001:20230511020903340"><Signature
xmlns="http://www.w3.org/2000/09/xmldsig#"><SignedInfo><CanonicalizationMethod
Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments"/><SignatureMethod
Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/><Reference URI=""><Transforms><Transform
Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/></Transforms><DigestMethod
Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/><DigestValue>Mj4XPMYTpeDas1GU0Po=</
DigestValue></Reference></
SignedInfo><SignatureValue>ZC3TXt0raBER8RBXRRFaZhZlYpyX0gxICTYaRAaPBmzN6T77I4eGtwAIHI
s3jug9i0urDNcVtBZR
5rAvrLt1aCzoYXAPFb22ab3sCTAo1bRg0z5N/g==</
SignatureValue><KeyInfo><X509Data><X509SubjectName>CN=DS eMudhra testAuthority,O=eMudhra
Limited,C=IN</X509SubjectName><X509Certificate>MIIGLTCCBRWgAwIBAgIEAVKfwjANBgkqhkiG9w0
BAQsFADCBgTELMAkGA1UEBhMCSU4xGDAWBgNV
BAoTD2VNdWRocmEgTGltaXRlZDEdMBsGA1UECxMUQ2VydGlmeWluZyBBdXRob3JpdHkxOTA3BgNV
BAMTMGUtTXVkaHJhIFN1YiBDQSBmb3IgQ2xhc3MgMyBEb2N1bWVudCBMjAyMjI
xMjM4NDRaFw0yNTAyMjExMjM4NDRaMIHUMQswCQYDVQQGEwJJTjEYMBYGA1UEChMP
ZGhyYSBMaW1pdGVkMR0wGwYDVQQLExRDZXJ0aWZ5aW5nIEF1dGhvcml0eTEPMA0GA1UEERMG
NTYwksJ1FwPF5PmCqnHxaXajoGx+XZOgChFR7sUzUTwG3rGDw929cPmipiLiYEhZo3P4cbS1OKC709
b+yrnOvywkaor/zxxFOlSfOErj6R+NcY5SY0hZVqrlwIfLij74b5JKtZAXVfadY5cZa6
7zUXuMt6ZL136dMPA0s4GBZC/tyOLfoI0nzKDw9f1nQWvJXlB60ikzepIK/FO6sTsexE+eCnoPn5
sytjqu/zAOcO/gJoPAsuTfsOygZTDiQygOfdIfQkFfKZy7uk57oEpGPt5F+itg==</X509Certificate></
X509Data></KeyInfo></Signature></SubAUAReq>

==== End ===

Version 1.1 Confidential Page 7 of 7

You might also like