ZOOP Digilocker Documentation

1 Introduction
2 Process Flow
3 End-User Flow
4 Developer Flow
- 4.1 Initialisation Call
  - 4.1.1 URL
    - 4.1.1.1 Example
  - 4.1.2 HEADER
  - 4.1.3 BODY
    - 4.1.3.1 Supported Document Types
    - 4.1.3.2 Fast Track Mode
  - 4.1.4 Response
    - 4.1.4.1 SUCCESS
    - 4.1.4.2 FAILURE
  - 4.1.5 What is the use of webhook_security_key?
  - 4.1.6 HEADER
  - 4.1.7 RESPONSE
- 4.2 Webhook Response
  - 4.2.1 Billing
- 4.3 SDK Integration
  - 4.3.1 Events in the SDK
    - 4.3.1.1 PAYLOAD
    - 4.3.1.2 close
    - 4.3.1.3 consent-denied
    - 4.3.1.4 digilocker-error
    - 4.3.1.5 digilocker-success
  - 4.3.2 Redirection Flow

Introduction

As a registered/licensed partner of Digilocker integrated with Requestor API, we can not only access/download the already fetched/pulled documents by the card-holder/end-user but also the Digital Locker Requestor workflow is a combination of web flow and supporting API.

Process Flow

Send the documents in the init call for which you want to pull the details of the end user and generate the request ID.
Provide the request ID in the SDK.
Invoke the function from the SDK to start an interaction.
A new browser tab will be opened which we call the start screen. The user will interact with it accordingly.
Once transaction completes two things happen. First we inform the SDK about the completion of the flow.
Secondly, we send a web-hook response to the response URL which you have send while creating the request ID.
You also have a REST API available to pull the status of a gateway transaction from your backend and reason for failure if any.

End-User Flow

From the SDK, the user will be navigated to ZOOP’s digilocker start page. If the user accepts the consent, they will be redirected to govt Digilocker portal.
If the user will continue by sharing his/her Aadhaar number and OTP sent to their registered phone number with Aadhaar.
On successful authentication, they will be redirected to Consent screen, where he/she authorises ZOOP.ONE to access/read/download the document(s).
They will be navigated to the Overview screen where they will view the list of Available and Unavailable documents.
The documents required by our Partner(B2B customer) which were shared in the init call will be pulled, if they are already present in the End-user / Card holder’s Digilocker Account.
If this list of required documents is not available on Digilocker, the end-user has to pull those directly from the Digilocker website.
For the available documents, the user can Preview the same.
Here, even if the user has one of the requested/required document available on Digilocker, they will be able to submit
After the submit the transaction is ended.

Developer Flow

For starters, you have to create an HTTP POST call – which we call the init call with the details about the transactions.

Initialisation Call

The Initialisation call is there to generate the request ID and give us the details about the transaction. It is an HTTP POST call with the body as the details about the transaction. Let’s see what is the URL and body look like.

URL

POST {{base_url}}/identity/digilocker/v1/init

Where the base_url can be either of them:

Production: https://live.zoop.plus
Test: https://test.zoop.plus

Example

https://live.zoop.plus/identity/digilocker/v1/init

HEADER

In order to authenticate you need to pass the following headers:

app-id - Identifier of your organisation which is created in client dashboard
api-key – API key generated for the respective app

BODY

{
  "docs": [
    "ADHAR",
    "PANCR",
    "RVCER",
    "DRVLC",
    "SSCER", // works in meripechaan flow only
    "HSCER"  // works in meripechaan flow only
  ], // At least one doctype is required
  "purpose": "<<purpose of the request>>, mandatory",
  "response_url": "<<webhook_url where the data will be send>>, mandatory",
  "redirect_url": "<<Gateway will be redirect to this URL with POST call>>, mandatory for REDIRECT mode",
  "fast_track": "<<either Y or N (default N)>>, optional",
  "pinless": true or false (default false)
}

The docs field should be an array and only accepted strings are the mentioned Doctype below.

Supported Document Types

Currently we support below mentioned eight document types but we have plans to add more in future.

Doctype	Belongs To
ADHAR	Aadhaar Card
DRVLC	Driving License
PANCR	PAN Verification Record
SSCER	Class X Marksheet `(Currently works meripechaan pinless only)`
HSCER	Class XII Marksheet `(Currently works meripechaan pinless only)`

Fast Track Mode

When you opt-in for the fast_track mode, the gateway flow will work little differently. In normal flow, when the user allows the consent on the Digilocker's consent page it is landed on a overview page. In that page we show which documents we were able to fetch and which we could not.

In the fast track mode, the overview page will not be visible to the user and the gateway will submit the transaction automatically. If any error in the transaction it won’t be able to process automatically.

Response

The response of successful init call is the JSON below with Content-Type: application/json.

SUCCESS

{
  "request_id": "<<transaction_id>>",
  "success": true,
  "webhook_security_key": "<<UUID>>",
  "request_timestamp": "2020-02-17T13:14:26.423Z",
  "expires_at": "2020-02-17T13:24:26.423Z",
  "sdk_url": "https://gateway.zoop.plus/digilocker/v1/start/<<transaction_id>>"
}

FAILURE

If for some reason, the init request fails then the body will be in the format mentioned.

{
    "success": false,
    "response_code": "106",
    "response_message": "Invalid ID Number or Combination of Inputs",
    "metadata": {
        "billable": "N",
        "reason_message": "INVALID-TYPE documents are not allowed"
    }
}

What is the use of `webhook_security_key`?

In the success response you will notice there is a webhook_security_key, you might be wondering what’s the use of this? It’s for security. The response_url that you specify in the init call should be a public URL so that we can make a request to that URL with data about the transaction. Now anyone can call that URL, even some malicious entity.

When we make a request to the response_url we specify an HTTP header named, same, webhook_security_key which will be same as we send in the response of the init call. For each calls the security key is different so you might need to store it somewhere while you receive the request from us.

The request_url that you send in the init call should be publicly accessible, that means anyone can call on that URL; in order to securely proceed you should first check webhook_security_key header which we send while sending the data on the request_url. It should be same as we send in the init call and proceed with the transaction only when they match.

GATEWAY URL

https://gateway.zoop.plus/digilocker/v1/start/{{requestId}}

This url will be used to trigger Digilocker web SDK and that you will get in the response itself.

Fetch Call

At any point after the request ID creation you wanted to know the status of the transaction, you can do that programmatically by making an HTTP GET request to us.

GET {{base_url}}/identity/digilocker/v1/fetch/{{requst_id}}

HEADER

In order to authenticate you need to pass the following headers:

app-id – This unique identifier given to each customer to the app/s.
api-key – This is an alphanumeric unique identifier for each app

RESPONSE

{
  "id": "{{request_id}}",
  "response_url": "<<your webhook URL>>",
  "env": "production",
  "purpose": "testing",
  "transaction_status": "SUCCESS",
  "webhook_sent": "N",
  "request_timestamp": "2022-02-01T04:20:51.315Z",
  "issued_docs": [
    "ADHAR",
    "PANCR"
  ],
  "pending_docs": [
    "RVCER",
    "DRVLC"
  ]
}

Webhook Response

After successful completion of the transaction the webhook response will be sent to the response_url. Below is the example format of the web-hook.

Note: Please don’t rely on the data_json property. This property is experimental and the format might change in future. This format is conversion of the data_xml to JSON format hence you can rely upon data_xml property more for the data.

{
  "request_id": "61fa3e0959b147868819b71a",
  "success": true,
  "response_code": "100",
  "response_message": "Transaction Successful",
  "metadata": {
    "billable": "Y"
  },
  "result": [
    {
      "issued": {
        "name": "Aadhaar Card",
        "type": "file",
        "size": "",
        "date": "30-09-2021",
        "parent": "",
        "mime": [
          "application/pdf"
        ],
        "uri": "<<uri of aadhaar>>",
        "doctype": "ADHAR",
        "description": "Aadhaar Card",
        "issuerid": "in.gov.uidai",
        "issuer": "Aadhaar, Unique Identification Authority of India"
      },
      "doctype": "ADHAR",
      "status": "FETCHED",
      "fetched_at": "2022-02-02T08:19:38.713Z",
      "data_xml": "<<xml of data>>",
      "data_pdf": "<<base64 of the document>>",
      "data_json": "<<json conversion of XML>>, !!EXPERIMENTAL!!"
    },
    {
      "issued": {
        "name": "PAN Verification Record",
        "type": "file",
        "size": "",
        "date": "20-09-2019",
        "parent": "",
        "mime": [
          "application/json",
          "application/xml",
          "application/pdf"
        ],
        "uri": "<<uri of pan>>",
        "doctype": "PANCR",
        "description": "PAN Verification Record",
        "issuerid": "in.gov.pan",
        "issuer": "Income Tax Department"
      },
      "doctype": "PANCR",
      "status": "FETCHED",
      "fetched_at": "2022-02-02T08:19:38.713Z",
      "data_xml": "<<xml of data>>",
      "data_pdf": "<<base64 of the document>>",
      "data_json": "<<json conversion of XML>>, !!EXPERIMENTAL!!"
    },
    {
      "doctype": "DRVLC",
      "status": "SKIPPED"
    },
    {
      "issued": {
        "name": "Registration of Vehicles",
        "type": "file",
        "size": "",
        "date": "20-09-2019",
        "parent": "",
        "mime": [
          "application/json",
          "application/xml",
          "application/pdf"
        ],
        "uri": "<<uri of rc>>",
        "doctype": "RVCER",
        "description": "Registration of Vehicles",
        "issuerid": "in.gov.transport",
        "issuer": "Ministry of Road Transport and Highways"
      },
      "doctype": "RVCER",
      "status": "FETCHED",
      "fetched_at": "2022-02-02T08:19:38.713Z",
      "data_xml": "<<xml of data>>",
      "data_pdf": "<<base64 of the document>>",
      "data_json": "<<json conversion of XML>>, !!EXPERIMENTAL!!"
    }
  ],
  "request_timestamp": "2022-02-02T08:17:13.648Z"
}

Billing

You will be billed based on the number of unique doctype you receive in the results array with status FETCHED. If the document is not present in the user’s account you will receive the status SKIPPED as you can see for the driving license in the example.

Note: There may be scenarios where the number of documents you receive will be more than one. For example, if the user has two RC linked with their digilocker account you will be billed for only one RC even if there are multiple RC in the webhook response.

SDK Integration

You can download the SDK (zoop-sdk.min.js) from our GitHub repository. There are two function calls to open the gateway. They should be called in the order mentioned in the docs. Firstly, to initiate the gateway you have to call zoop.initDigilockerGateway() with the gateway option. The next step would be to open the gateway. That can be done by simply calling zoop.openDigilockerGateway() with the request ID generated in the init call. For your ease we have also added one sample example below:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Your Site</title>
  </head>
  <body>
    <!-- And add the code below into the body of your HTML -->
    <div id="zoop-gateway-model">
      <div id="zoop-model-content"></div>
    </div>
    <script src="./zoop-sdk.min.js"></script>
    <button onclick="openGateway()">Open</button>
    <script type="application/javascript">
      // Name of the this function can be anything you want.
      function openGateway() {
         // To setup gateway UI to mach your application you can
         // pass the gateway options but the support for it will be
         // added soon
         zoop.initDigilockerGateway({
           mode: "<<TAB | REDIRECT>>" // default TAB, but choose either of them
         });
         // Pass the transaction ID created at Init call
         zoop.openDigilockerGateway("<<request_id>>");
      }
    </script>
  </body>
</html>

Supported gateway modes are TAB and REDIRECT only. In tab mode the transaction will open in a new tab and after completion the opened tab will be closed. In the REDIRECT mode the transaction will start in the same page and after completion it will be redirected to the redirect_url provided in the init call.

Events in the SDK

Events notify our SDK users about an event that was triggered. The event handling is uniform for all the events. If you have chosen to use the redirect flow please look at the Redirection Flow.

<script>
  zoop.on("close", (message) => {
    // handle the event
  });
  zoop.on("consent-denied", (message) => {
    // handle the event
  });
  zoop.on("gateway-error", (message) => {
    // handle the event
  });
  zoop.on("digilocker-success", (message) => {
    // handle the success event
  });
  zoop.on("digilocker-error", (message) => {
    // handle the failure event
  });
</script>

This is the list of events for Digilocker.

Event Name	Occurs When

Event Name	Occurs When
`close`	When the user closes the gateway after clicking on submit.
`consent-denied`	When user denies to it's consent for e-sign.
`gateway-error`	When some error while interacting with gateway.
`digilocker-success`	When Digilocker is successful
`digilocker-error`	When Digilocker fails

PAYLOAD

These are the payload for events which has payload supported.

`close`

After submitting the request the user has to wait for a long time in some cases. We also give the user to close the gateway after 30 seconds. In that case you will receive this response in the SDK.

{
  "response_message": "waiting_to_finish"
}

`consent-denied`

On the start page if the user don’t want to continue with the transaction they can deny the consent. The following error response will be sent in that case.

{
  "success": false,
  "response_code": "104",
  "response_message": "Invalid ID Number or Combination of Inputs",
  "metadata": {
    "billable": "N",
    "reason_code": "CSD",
    "reason_message": "User denied consent"
  },
  "result": null,
  "request_timestamp": null,
  "response_timestamp": null
}

gateway-error

When the user is interacting with the gateway and encounters any kind of error while opening it we close the gateway and call this event. The payload for this can be the following:

{
  "success": false,
  "response_code": "106",
  "response_message": "Invalid ID Number or Combination of Inputs",
  "metadata": {
    "billable": "N",
    "reason_code": "THE",
    "reason_message": "The transaction was valid for 30 minutes only."
  },
  "result": null,
  "request_timestamp": null,
  "response_timestamp": null
}

`digilocker-error`

This error happens when there is issue from the Digilocker portal.

{
  "success": false,
  "response_code": "106",
  "response_message": "Invalid ID Number or Combination of Inputs",
  "metadata": {
    "billable": "N",
    "reason_code": "DE",
    "reason_message": "Oops! That was uncertain. Please start over again"
  },
  "result": null,
  "request_timestamp": null,
  "response_timestamp": null
}

`digilocker-success`

If the digilocker documents have been successfully submitted, the transaction will be closed with below example payload.

{
  "request_id": "61fa3e0959b147868819b71a",
  "success": true,
  "response_code": "100",
  "response_message": "Transaction Successful",
  "metadata": {
    "billable": "Y"
  },
  "result": [
    {
      "issued": {
        "name": "Aadhaar Card",
        "type": "file",
        "size": "",
        "date": "30-09-2021",
        "parent": "",
        "mime": [
          "application/pdf"
        ],
        "uri": "<<uri of aadhaar>>",
        "doctype": "ADHAR",
        "description": "Aadhaar Card",
        "issuerid": "in.gov.uidai",
        "issuer": "Aadhaar, Unique Identification Authority of India"
      },
      "doctype": "ADHAR",
      "status": "FETCHED",
      "fetched_at": "2022-02-02T08:19:38.713Z"
    },
    {
      "issued": {
        "name": "PAN Verification Record",
        "type": "file",
        "size": "",
        "date": "20-09-2019",
        "parent": "",
        "mime": [
          "application/json",
          "application/xml",
          "application/pdf"
        ],
        "uri": "<<uri of pan>>",
        "doctype": "PANCR",
        "description": "PAN Verification Record",
        "issuerid": "in.gov.pan",
        "issuer": "Income Tax Department"
      },
      "doctype": "PANCR",
      "status": "FETCHED",
      "fetched_at": "2022-02-02T08:19:38.713Z"
    },
    {
      "issued": {
        "name": "Driving License",
        "type": "file",
        "size": "",
        "date": "20-09-2019",
        "parent": "",
        "mime": [
          "application/json",
          "application/xml",
          "application/pdf"
        ],
        "uri": "<<uri of dl>>",
        "doctype": "DRVLC",
        "description": "Driving License",
        "issuerid": "in.gov.transport",
        "issuer": "Ministry of Road Transport and Highways"
      },
      "doctype": "DRVLC",
      "status": "FETCHED",
      "fetched_at": "2022-02-02T08:19:38.713Z"
    },
    {
      "issued": {
        "name": "Registration of Vehicles",
        "type": "file",
        "size": "",
        "date": "20-09-2019",
        "parent": "",
        "mime": [
          "application/json",
          "application/xml",
          "application/pdf"
        ],
        "uri": "<<uri of rc>>",
        "doctype": "RVCER",
        "description": "Registration of Vehicles",
        "issuerid": "in.gov.transport",
        "issuer": "Ministry of Road Transport and Highways"
      },
      "doctype": "RVCER",
      "status": "FETCHED",
      "fetched_at": "2022-02-02T08:19:38.713Z"
    }
  ],
  "request_timestamp": "2022-02-02T08:17:13.648Z"
}

Redirection Flow

In the redirection flow, instead of notifying the completion of the gateway to the SDK we redirect the gateway to the redirect_url provided in the Init call. For the redirection flow, you must provide the mode as "REDIRECT" in the initDigilockerGateway function call.

You will see an error if you don’t provide the redirect_url in the init call and open the gateway in the REDIRECT mode through SDK.

After the completion of the transaction, either success or failure we will redirect the gateway to the provided redirect_url with an HTTP POST call with content-type application/x-www-form-urlencoded. For clarity, we have added a cURL request below.

curl --location --request POST 'https://example.com/digilocker/redirection?action=digilocker-success' \
--header 'content-type: application/x-www-form-urlencoded' \
--data-urlencode 'payload={"request_id":"61fa3e0959b147868819b71a","success":true,"response_code":"100","response_message":"Transaction Successful","metadata":{"billable":"Y"},"result":[{"issued":{"name":"Aadhaar Card","type":"file","size":"","date":"30-09-2021","parent":"","mime":["application/pdf"],"uri":"<<uri of aadhaar>>","doctype":"ADHAR","description":"Aadhaar Card","issuerid":"in.gov.uidai","issuer":"Aadhaar, Unique Identification Authority of India"},"doctype":"ADHAR","status":"FETCHED","fetched_at":"2022-02-02T08:19:38.713Z"},{"issued":{"name":"PAN Verification Record","type":"file","size":"","date":"20-09-2019","parent":"","mime":["application/json","application/xml","application/pdf"],"uri":"<<uri of pan>>","doctype":"PANCR","description":"PAN Verification Record","issuerid":"in.gov.pan","issuer":"Income Tax Department"},"doctype":"PANCR","status":"FETCHED","fetched_at":"2022-02-02T08:19:38.713Z"},{"issued":{"name":"Driving License","type":"file","size":"","date":"20-09-2019","parent":"","mime":["application/json","application/xml","application/pdf"],"uri":"<<uri of dl>>","doctype":"DRVLC","description":"Driving License","issuerid":"in.gov.transport","issuer":"Ministry of Road Transport and Highways"},"doctype":"DRVLC","status":"FETCHED","fetched_at":"2022-02-02T08:19:38.713Z"},{"issued":{"name":"Registration of Vehicles","type":"file","size":"","date":"20-09-2019","parent":"","mime":["application/json","application/xml","application/pdf"],"uri":"<<uri of rc>>","doctype":"RVCER","description":"Registration of Vehicles","issuerid":"in.gov.transport","issuer":"Ministry of Road Transport and Highways"},"doctype":"RVCER","status":"FETCHED","fetched_at":"2022-02-02T08:19:38.713Z"}],"request_timestamp":"2022-02-02T08:17:13.648Z"}'

In the URL we will include an action query parameter which will be Event Name and the data of URL encoded value will be the payload that you generally receive in the SDK.

ZOOP Digilocker Documentation

Introduction

Process Flow

End-User Flow

Developer Flow

Initialisation Call

URL

Example

HEADER

BODY

Supported Document Types

Fast Track Mode

Response

SUCCESS

FAILURE

What is the use of webhook_security_key?

HEADER

RESPONSE

Webhook Response

Billing

SDK Integration

Events in the SDK

PAYLOAD

close

consent-denied

digilocker-error

digilocker-success

Redirection Flow

What is the use of `webhook_security_key`?

`close`

`consent-denied`

`digilocker-error`

`digilocker-success`