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

# KYC SDK

KYC SDK is DollarPe’s hosted verification flow. Generate a KYC link for your user, redirect them to it, and receive the result over webhook. You don’t need to build verification workflows or handle identity documents.

## Customer journey

```mermaid theme={null}
flowchart TD
    Start([Start Integration]):::startEndNode --> CreateCustomer[Create Customer Profile]:::mainNode
    CreateCustomer -->|API Call| CustomerAPI[/API: /customer/create/]:::apiNode
    
    CustomerAPI --> GenerateKycLink[Generate KYC Link]:::mainNode
    GenerateKycLink -->|API Call| KycURL[/API: /kyc/generate-link/]:::apiNode
    KycURL --> CompleteKYC[User Completes KYC on URL]:::mainNode

    CompleteKYC --> AutoApproved[KYC Auto Approved]:::stateNode
    CompleteKYC --> AutoDeclined[KYC Auto Declined]:::failureNode
    CompleteKYC --> ManualReview[KYC in Manual Review]:::waitNode

    AutoApproved --> AddBank[Add Bank Account]:::mainNode
    AutoDeclined --> GenerateKycLink

    ManualReview --> ManuallyApproved[KYC Manually Approved]:::stateNode
    ManualReview --> ManuallyDeclined[KYC Manually Declined]:::failureNode

    ManuallyApproved --> AddBank
    ManuallyDeclined --> GenerateKycLink

    AddBank -->|API Call| BankAPI[/API: /bank/add-account/]:::apiNode
    BankAPI --> Complete[Begin Transactions]:::mainNode
    Complete --> TransactionReady([Integration Complete]):::startEndNode

    classDef startEndNode fill:#dcedc8,stroke:#558b2f,stroke-width:2px,color:#000
    classDef mainNode fill:#e3f2fd,stroke:#1976d2,stroke-width:2px,color:#000
    classDef apiNode fill:#ede7f6,stroke:#5e35b1,stroke-width:2px,color:#000
    classDef stateNode fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#000
    classDef failureNode fill:#ffebee,stroke:#c62828,stroke-width:2px,color:#000
    classDef waitNode fill:#fff8e1,stroke:#ff8f00,stroke-width:2px,color:#000
```

<Note> Verification typically takes 60 seconds to 2 hours. Design your user experience accordingly. </Note>

### Generate a KYC link

Once the customer profile is created, generate their KYC link.

<Warning>
  Documents required: Aadhaar or Passport, and PAN number.
</Warning>

<Tabs>
  <Tab title="API Request">
    ```javascript theme={null}
    POST /kyc/generate-link
    {
      "customer_id": "075986f3-282b-4555-bfcd-fad973e32596",
      "redirect_url": "https://..."
    }
    ```
  </Tab>

  <Tab title="Response">
    ```json theme={null}
    {
      "status": true,
      "message": "Success",
      "data": {
          "customer_id": "075986f3-282b-4555-bfcd-fad973e32596",
          "url": "https://..."
      }
    }
    ```
  </Tab>
</Tabs>

<Tip>
  If you collect KYC data yourself, see the [KYC Sharing](/guides/integration-guides/kyc/kyc-sharing) method instead.
</Tip>

### Verification process

The SDK runs three checks in sequence.

#### Step 1: PAN verification

The user enters their full name, date of birth, and PAN number.

In the background:

* PAN validity is checked against official government sources.
* PAN category is confirmed as individual (not a company).
* Name and DOB are matched against official PAN records.
* Aadhaar linkage status of the PAN is checked.

<Note>
  The flow only proceeds to document verification after PAN passes.
</Note>

#### Step 2: Document verification

The user picks an identity document: Aadhaar or Passport.

Aadhaar: OTP-based authentication via DigiLocker. Data is fetched directly, no manual upload needed.

Passport: The user uploads front and back pages. Forgery detection runs on the image, OCR extracts name, date of birth, and passport number, and results are cross-checked against government data where available.

Name and DOB from PAN are then matched with the document.

#### Step 3: Liveness and face match

The user takes a live selfie. The system confirms it is not a static photo, then compares the selfie against the photo on the submitted document using biometric matching.

#### Final outcome

If all three steps pass, KYC status is set to `VERIFIED`. The user can then link a bank account and begin transactions.

### Track verification status

After submitting, verification typically takes 60 seconds to 2 hours.

#### Webhooks (recommended)

Configure a webhook endpoint to receive status updates:

```javascript theme={null}
// Sample webhook payload
{
  "type": "CUSTOMER",
  "event": "FAILED",
  "id": "12348400-e29b-41d4-a716-446655440000",
  "timestamp": "2024-03-13T10:00:00Z",
  "metadata": {
    "failure_reason": "TAX_VERIFICATION_FAILED"
  }
}
```

#### Polling

If webhooks aren't an option, poll the customer endpoint:

<Tabs>
  <Tab title="API Request">
    ```javascript theme={null}
    GET /customer/{customer_id}
    ```
  </Tab>

  <Tab title="Response">
    ```json theme={null}
    {
      "status": true,
      "message": "Success",
      "data": {
          "id": "075986f3-282b-4555-bfcd-fad973e32596",
          "client_reference_id": "cus_12345abcde",
          "full_name": "JOHN DOE",
          "email": "john@example.com",
          "phone": "+919911002211",
          "country": "IND",
          "type": "INDIVIDUAL",
          "status": "UNVERIFIED",
          "failure_reason": null
      }
    }
    ```
  </Tab>
</Tabs>

<Tip>
  If using the polling approach, we recommend checking no more frequently than once every 60 seconds to avoid API rate limits.
</Tip>

### Handle verification issues

If verification fails, re-generate the KYC link and ask the user to resubmit.