Table of Contents
1. API Objective #
This RESTful API helps to mask Aadhaar Number from Aadhaar Card images. Consuming application will request A48 API with image detail in following XML format and in response API will return back Aadhaar Number redacted image in base 64 encoded string.
2. Request Details #
URL: http:///crmapi/TrackwizzWebApi/A48/MaskAadhaarNumber
needs to be replaced by actual DNS URL for TrackWizz CRM API that is deployed.
HTTP Request Type: POST
Request Headers:
Content-Type: application/xml
3.1 Sample Request #
<?xml version="1.0" encoding="utf-8"?> <A48AadhaarNumberMaskingRequest> <ApiToken>38c0dc75-4fd8-4765-86c6-7d561d12dd80</ApiToken> <RequestId>ABC1234</RequestId> <SessionKey>EAMyfrjANBgkqCBkzr2ZLVncZb3uf86EzPWUEaqwTfg</SessionKey> <RequestData>f86EzPWUEaqwTEAMyfrjA9w0BAQsFADCBkzr2ZLVncZb3u</RequestData> </A48AadhaarNumberMaskingRequest>
3.2 Sample Decrypted RequestData #
<?xml version="1.0" encoding="utf-8"?> <RequestData> <ParentCompany>ABC PVT LTD</ParentCompany> <ApplicationFormNo>AF123</ApplicationFormNo> <RecordIdentifier>123</RecordIdentifier> <SourceSystem>Finacle</SourceSystem> <ImageType>JPEG</ImageType> <ImageData>PWUEaqwTEAMyfrjANBgkqhkiG9Bkzr2ZLVncZb3uFADCBkzr2ZLVncZb3u</ImageData> <MaskingType>MT3</MaskingType> <AttachmentType>AadharCard</AttachmentType> </RequestData>
4. Request Parameter Description #
Table 1: Request – Main
| Field Name / XML Tag | Mandatory | Data Type | Length | Remarks |
| ApiToken | Yes | String | 60 | To be shared by TrackWizz |
| RequestId | Yes | String | 60 | Needs to be unique. |
| SessionKey | Yes | String | ||
| RequestData | Yes | String |
Table 2: RequestData
| Field Name / XML Tag | Mandatory | Data Type | Length | Remarks |
| ParentCompany | Yes | String | 100 | |
| ApplicationFormNo | No | String | 60 | |
| RecordIdentifier | No | String | 60 | |
| SourceSystem | No | String | 60 | |
| ImageType | Yes | String | 300 | Possible Values will be .jpeg, .jpg, .tiff, .tif, .bmp, .pdf. |
| MaskingType | Yes | String | 100 | Values should be as per Table 3 |
| ImageData | Yes | String | NA | Image should be base 64 encoded string. |
| AttachmentType | No | String | 100 | Values should be as per Table 4 (If value is not passed then AadharCard will be default value) |
Table 3: Masking Type
| Code | Description |
| MT3 | It will mask all 12-digits of Aadhaar number. |
| MT4 | It will mask first 10-digits of Aadhaar number. |
| MT5 | It will mask first 8-digits of Aadhaar number. |
Table 4: Attachment Type
|
AadharCard |
|
AOFWithKYC |
|
AadhaarOffline |
|
EKYCAuthImage |
5. Request Encryption Steps #
Consider Data to be Encrypted is
<?xml version="1.0" encoding="utf-8"?> <RequestData> <ParentCompany>ABC PVT LTD</ParentCompany> <ApplicationFormNo>AF123</ApplicationFormNo> <RecordIdentifier>123</RecordIdentifier> <SourceSystem>Finacle</SourceSystem> <ImageType>JPEG</ImageType> <ImageData>PWUEaqwTEAMyfrjANBgkqhkiG9Bkzr2ZLVncZb3uFADCBkzr2ZLVncZb3u</ImageData> <MaskingType>MT3</MaskingType> <AttachmentType>AadharCard</AttachmentType> </RequestData>
Following are the steps to be followed for encryption
1.Generate a Session Key of 256 bit.
2.Encrypt the data using AES (Symmetric Algorithm) using the above generated Session Key
3.Encode the above encrypted data to Base64 string. Example: The above sample data would look like following: f86EzPWUEaqwTEAMyfrjANBgkqhkiG9w0BAQsFADCBkzr2ZLVncZb3u
4.Encrypt the session key using Public Key of the Receiver, using RSA (Asymmetric Algorithm)
5.Encode the above encrypted Session Key to Base64 string.
6.Add this encrypted and encoded data and Session Key to the request XML. Example: The request would look like following:
<?xml version="1.0" encoding="utf-8"?> <A48AadhaarNumberMaskingRequest> <ApiToken>38c0dc75-4fd8-4765-86c6-7d561d12dd80</ApiToken> <RequestId>ABC1234</RequestId> <SessionKey>EAMyfrjANBgkqhkiG9w0ADCBkzr2ZLVncZb3uf86EzPWUEaqwTfg</SessionKey> <RequestData>f86EzPWUEaqwTEAMyBgkqhkiG9w0BAQsFADCBkzr2ZLVncZb3u</RequestData> </A48AadhaarNumberMaskingRequest>
7.Using the Private Key of the Sender, sign the entire request XML. The request will look like following:
<?xml version="1.0" encoding="utf-8"?> <A48AadhaarNumberMaskingRequest> <ApiToken>38c0dc75-4fd8-4765-86c6-7d561d12dd80</ApiToken> <RequestId>ABC1234</RequestId> <SessionKey>EAMyfrjANBgkqhkiG9w0BAQsFAVncZb3uf86EzPWUEaqwTfg</SessionKey> <RequestData>f86EzPWUEaqwTEAMyfrjAN9w0BAQsFADCBkzr2ZLVncZb3u</RequestData> <Signature xmlns="http://www.w3.org/2000/09/xmldsig#"> <SignedInfo> <CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315" /> <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>bWYkKQBqU24KZSNhDdPZBZVLotM=</DigestValue> </Reference> </SignedInfo> <SignatureValue> db0YWFoIwow9iDTuoHXtPPVTpMXi20ny1+TYYyvesYZ67dkZ2P1FTV43zdICibsEfnJrAnWD Ly8QORlcui9f4CGWnHCccID3dPeQ== </SignatureValue> <KeyInfo> <X509Data> <X509SubjectName>Details</X509SubjectName> <X509Certificate>MIIGCTCCBPGgAwIBAgIEAMyfrjANBgkqhkiG9w0BAQsFADCBkzr2ZLVncZb3uf86EzPWUEaqwTfgGYdE2xhU/phUn+2Zyvc9nfQQ==</X509Certificate> </X509Data> </KeyInfo> </Signature> </A48AadhaarNumberMaskingRequest>
6. Sample Success Response #
<?xml version="1.0" encoding="utf-8"?> <A48AadhaarNumberMaskingResponse> <RequestId>ABC1234</RequestId> <SessionKey>EAMyfrjANBgkqhkiG9w0BCBkzr2ZLVncZb3uf86EzPWUEaqwTfg</SessionKey> <ResponseData>fEaqwTEAMyfrjANBgkkiG9w0BAQsFADCBkzr2ZLVncZb3u</ResponseData> <RequestStatus>AcceptedByTW</RequestStatus> </A48AadhaarNumberMaskingResponse>
7. Sample Failure Response #
<?xml version="1.0" encoding="utf-8"?> <A48AadhaarNumberMaskingResponse> <RequestId>ABC1234</RequestId> <RequestStatus>RejectedByTW</RequestStatus> <RejectionCode>EC123</RejectionCode> <RejectionDescription>Parent Company is mandatory.</RejectionDescription> </A48AadhaarNumberMaskingResponse>
8. Sample Decrypted ResponseData #
<?xml version="1.0" encoding="utf-8"?> <ResponseData> <ApplicationFormNo>AF123</ApplicationFormNo> <RecordIdentifier>123</RecordIdentifier> <MaskingStatus>Masked</MaskingStatus> <PageMaskingStatusDetails> <PageMaskingStatus> <PageNo>1</PageNo> <Status>Masked</Status> </PageMaskingStatus> <PageMaskingStatus> <PageNo>2</PageNo> <Status>Masked</Status> </PageMaskingStatus> </PageMaskingStatusDetails> <MaskedImage>dgdNBgkkiG9w0BAQsFADCBtop43tgNBgkkiG9ret54364h</MaskedImage> </ResponseData>
9. Response Parameter Description #
Table 5: Response – Main
| Field Name/XML Tag | Mandatory | Data Type | Length | Remarks |
| RequestId | Yes | String | 60 | Same as incoming Request |
| RequestStatus | Yes | String | 60 | Possible Values: Accepted byTW/Rejected byTW |
| RequestRejectionCode | No | String | 60 | |
| RequestRejectionDescription | No | String | 500 | |
| SessionKey | No | String | ||
| ResponseData | No | String |
Table 6: ResponseData
| Field Name/XML Tag | Mandatory | Data Type | Length | Remarks |
| MaskingStatus | Yes | String | 60 | Possible values: Masked/NotMasked/ MaybeMasked/ AlreadyMasked/ NotIdentified . |
| MaskedImage | Yes | String | 60 | Masked Image will be base 64 encoded string. |
| ApplicationFormNo | No | String | 60 | |
| RecordIdentifier | No | String | 60 | |
| PageMaskingStatusDetails | No | Complex | Contains multiple PageMaskingStatus |
Table 7: PageMaskingStatus (Can be multiple in one PageMaskingStatusDetails)
| Field Name/XML Tag | Mandatory | Data Type | Length | Remarks |
| PageNo | Yes | Integer | ||
| Status | Yes | String | 60 | Possible values: Masked/NotMasked/ MaybeMasked/ AlreadyMasked/ NotIdentified. |
10. Response Decryption Steps #
Consider the following response for the above request made to a system
<?xml version="1.0" encoding="utf-8"?> <A48AadhaarNumberMaskingResponse> <RequestId>ABC1234</RequestId> <SessionKey>EAMyfrjANBgkqhkiG9w0BCBkzr2ZLVncZb3uf86EzPWUEaqwTfg</SessionKey> <ResponseData>fEaqwTEAMyfrjANBgkkiG9w0BAQsFADCBkzr2ZLVncZb3u</ResponseData> <RequestStatus>AcceptedByTW</RequestStatus> <Signature xmlns="http://www.w3.org/2000/09/xmldsig#"> <SignedInfo> <CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/> <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>3ih3dWLJZJMie0HUtenMuZR1/AI=</DigestValue> </Reference> </SignedInfo> <SignatureValue> HKDnPRlelk2qu/Yx8Q6YH8TaHdyCmqjZRJ+TNqPbit5xXQ563BNN4Rs4rTrheI8yfFRnhTTCZtJuC98r5p508Yu/w== </SignatureValue> </Signature> </A48AadhaarNumberMaskingResponse>
Following are the steps to decrypt and read the response
1.Verify the signature in Response XML using Sender’s Public Key
2.Decode the Session Key from the Response XML.
3.Decrypt the above Session Key by Receiver’s Private Key using RSA (Asymmetric Algorithm)
4.Decode the data in Response XML.
5.Decrypt the data by Session Key (derived from above) using AES (Symmetric Algorithm).
After the above decryption the ResponseData in Response XML will look like follows:
<?xml version="1.0" encoding="UTF-8" ?> <ResponseData> <ApplicationFormNo>AF123</ApplicationFormNo> <RecordIdentifier>123</RecordIdentifier> <MaskingStatus>Masked</MaskingStatus> <MaskedImage>dgdNBgkkiG9w0BAQsFADCBtop43tgNBgkkiG9ret54364h</MaskedImage> </ResponseData>
| Error code | Description |
| EC2334 | API Token is mandatory |
| EC1492 | The employee does not have access to API in Employee Master |
| RC91 | Request Id is mandatory |
| RC92 | Invalid RequestId length. |
| RC93 | RequestId should be unique for given API token. |
| EC2322 | Session Key is Mandatory |
| EC2323 | Request Data is Mandatory |
| EC1188 | ParentCompany is Mandatory |
| EC1189 | ParentCompany should be as per the "Company Internal Code" in Company Parent Master |
| EC100 | ImageType is Mandatory |
| EC2329 | ImageType should be as per given enumeration. |
| EC2325 | ImageData is Mandatory |
| EC2330 | Image size is more than the expected one |
| EC2115 | MaskingType is Mandatory |
| EC2116 | Masking Type should be as per given enumeration |
| EC2332 | Could not verify request signature. |
| EC2333 | Encryption Provider is not Specified in Employee Master |
| EC2335 | IP Address is not whitelisted |
| RC98 | SourceSystemName does not exist in TrackWizz. |
| RC115 | Invalid SourceSystemName Length. |
| RC673 | Invalid RecordIdentifier Length |
| RC674 | Invalid ApplicationFormNo Length |
| EC2531 | AttachmentType should be as per given enumeration |
