> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stablepay.global/llms.txt
> Use this file to discover all available pages before exploring further.

# Verify DigiLocker

> DigiLocker-based Aadhaar verification

# DigiLocker Verification

DigiLocker verification allows users to share their Aadhaar and PAN documents directly from the government DigiLocker service. This is a more user-friendly alternative to Aadhaar OTP verification.

## Flow Overview

1. **Initialize** - Get a DigiLocker consent URL
2. **User Consent** - User opens URL and grants consent in DigiLocker app
3. **Check Status** - Poll status until verification completes

## Initialize DigiLocker Session

<ParamField body="redirectUrl" type="string">
  Optional URL to redirect user after DigiLocker consent
</ParamField>

<ParamField body="deviceId" type="string">
  Device fingerprint/ID for FIU compliance. Must be captured from the client device.
</ParamField>

### Request

```bash theme={null}
curl -X POST https://api.stablepay.global/v2/users/usr_abc123/kyc/digilocker/init \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "redirectUrl": "https://yourapp.com/kyc/callback",
    "deviceId": "device-fingerprint-12345"
  }'
```

### Response

```json theme={null}
{
  "success": true,
  "data": {
    "clientId": "digilocker_abc123xyz",
    "url": "https://digilocker-sdk.notbot.in/?gateway=production&type=digilocker&token=...",
    "expiresIn": 600,
    "message": "DigiLocker URL generated. Open this URL for user to complete verification."
  }
}
```

<Note>
  Direct the user to the `url` to complete DigiLocker consent. The session expires in 10 minutes.
</Note>

## Check DigiLocker Status

Poll this endpoint to check if the user has completed DigiLocker consent.

### Request

```bash theme={null}
curl -X GET https://api.stablepay.global/v2/users/usr_abc123/kyc/digilocker/status?clientId=digilocker_abc123xyz \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (Verified)

```json theme={null}
{
  "success": true,
  "data": {
    "status": "VERIFIED",
    "verified": true,
    "aadhaar": {
      "name": "RAHUL SHARMA",
      "dob": "1990-05-15",
      "gender": "M",
      "address": "123 Main Street, Mumbai, Maharashtra",
      "maskedAadhaar": "XXXX-XXXX-1234",
      "pincode": "400001",
      "state": "Maharashtra",
      "district": "Mumbai"
    },
    "pan": {
      "number": "ABCDE1234F",
      "name": "RAHUL SHARMA"
    }
  }
}
```

### Response (Pending)

```json theme={null}
{
  "success": true,
  "data": {
    "status": "PENDING",
    "verified": false,
    "message": "Waiting for user to complete DigiLocker verification"
  }
}
```

### Response (Expired)

```json theme={null}
{
  "success": false,
  "data": {
    "status": "EXPIRED",
    "verified": false,
    "error": "DigiLocker session has expired. Please generate a new token."
  }
}
```

## Status Values

| Status     | Description                                   |
| ---------- | --------------------------------------------- |
| `PENDING`  | User has not completed DigiLocker consent yet |
| `VERIFIED` | Verification complete, Aadhaar data available |
| `FAILED`   | User cancelled or verification failed         |
| `EXPIRED`  | Session expired before completion             |

## Benefits Over Aadhaar OTP

| Feature         | DigiLocker                | Aadhaar OTP        |
| --------------- | ------------------------- | ------------------ |
| User Experience | Single consent flow       | Enter OTP manually |
| Document Access | Aadhaar + PAN in one flow | Aadhaar only       |
| Security        | OAuth 2.0 based           | SMS OTP            |
| Consent Record  | Government maintained     | None               |

## Errors

| Code                  | Description                                |
| --------------------- | ------------------------------------------ |
| `SESSION_NOT_FOUND`   | Invalid clientId or session expired        |
| `ALREADY_VERIFIED`    | DigiLocker already verified for this user  |
| `SERVICE_UNAVAILABLE` | DigiLocker service temporarily unavailable |