> ## 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 sharing

KYC sharing lets you run identity verification with your own infrastructure. You collect and verify the user’s documents, then submit the verified data to DollarPe via API. DollarPe stores the data and runs its own compliance checks.

Use this method if you already have an established KYC process and don’t need DollarPe to manage document collection.

## Customer journey

```mermaid theme={null}
flowchart TD
    Start([Start Integration]) --> CreateCustomer[Create Customer Profile]
    CreateCustomer -->|API Call| CustomerAPI[/API: /customer/create/]
    
    CustomerAPI --> KYCConfiguration[Get KYC Configuration]
    KYCConfiguration -->|API Call| KYCConfigurationAPI[/API: /kyc/configuration/]

    KYCConfigurationAPI --> AddKYC[Submit KYC Data]
    AddKYC -->|API Call| KycAPI[/API: /kyc/add-kyc-data/]
    KycAPI --> Processing[KYC PROCESSING State]
    
    Processing --> WebhookNotification[Webhook Notification]
    WebhookNotification --> Verification{Verification Result}
    
    Verification -->|Success| Verified[KYC State: VERIFIED]
    Verification -->|Failure| Failed[KYC State: FAILED]
    
    Failed --> AttemptsCheck{Any attempts left?}
    AttemptsCheck -->|No| Blocked[Customer Blocked]
    AttemptsCheck -->|Yes| CheckReason{Check Failure Reason}
    
    CheckReason -->|Tax Number Issue| UpdateTax[Update Tax Info]
    UpdateTax -->|API Call| TaxAPI[/API: /kyc/update-tax-info/]
    TaxAPI --> Processing
    
    CheckReason -->|Document Issue| UpdateDoc[Update Document Info]
    UpdateDoc -->|API Call| DocAPI[/API: /kyc/update-document-info/]
    DocAPI --> Processing

    CheckReason -->|Additional Info Issue| UpdateAdditionalInfo[Update Additional Info]
    UpdateAdditionalInfo -->|API Call| AdditionalAPI[/API: /kyc/update-additional-info/]
    AdditionalAPI --> Processing
    
    Verified --> AddBank[Add Bank Account]
    AddBank -->|API Call| BankAPI[/API: /bank/add-account/]
    BankAPI --> Complete[Begin Transactions]
    Complete --> TransactionReady([Integration Complete])

    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:#f3e5f5,stroke:#8e24aa,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
    classDef blockNode fill:#ef9a9a,stroke:#b71c1c,stroke-width:2px,color:#000

    class Start,TransactionReady startEndNode
    class CreateCustomer,KYCConfiguration,AddKYC,UpdateTax,UpdateDoc,UpdateAdditionalInfo,AddBank,Complete mainNode
    class CustomerAPI,KYCConfigurationAPI,KycAPI,TaxAPI,DocAPI,AdditionalAPI,BankAPI apiNode
    class Processing,Verified stateNode
    class Failed,CheckReason,AttemptsCheck failureNode
    class Blocked blockNode
    class WebhookNotification waitNode
```

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

### Submitting KYC Information

#### Fetching KYC configuration

Fetch the KYC configuration to get supported document types and required additional fields using the [/kyc/configuration/{customer_id}](/api-reference-exchange/endpoint/kyc/configuration-\{customer_id}) endpoint.

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

  <Tab title="Response">
    ```json theme={null}
    {
      "status": true,
      "message": "Success",
      "data": {
          "supported_document_types": [
            "AADHAAR", "PASSPORT", "VOTER_ID", "DRIVING_LICENSE"
          ],
          "additional_info_required": {
              "options": [
                  "income_range",
                  "profession"
              ],
              "rules": {
                  "type": "allOf",
                  "min_required": 2
              },
              "income_range": {
                  "type": "string",
                  "required": true
              },
              "profession": {
                  "type": "string",
                  "required": true
              }
          }
      }
    }
    ```
  </Tab>
</Tabs>

Key fields:

* `supported_document_types`: Valid values for `document_type` in [/kyc/add-kyc-data](/api-reference-exchange/endpoint/kyc/add-kyc-data)
* `additional_info_required`: Describes the `additional_info` fields required in [/kyc/add-kyc-data](/api-reference-exchange/endpoint/kyc/add-kyc-data)
  * `options`: Available values for `{field_name}`
  * `rules`: Contains `type` (`anyOf`, `allOf`) and `min_required` — the minimum number of fields to include
  * `{field_name}`: Contains `type` (`string`, `url`) and `required` — whether that field is mandatory

#### Adding KYC data

Collect and submit KYC details using the [/kyc/add-kyc-data](/api-reference-exchange/endpoint/kyc/add-kyc-data) API.

<Warning>
  Document requirements: clear, high-resolution images with legible text. Supported types: AADHAAR, PASSPORT, VOTER\_ID, DRIVING\_LICENSE. The customer's face must be clearly visible.
</Warning>

<Tabs>
  <Tab title="API Request">
    ```javascript theme={null}
    POST /kyc/add-kyc-data
    {
      "customer_id": "075986f3-282b-4555-bfcd-fad973e32596",
      "full_name": "John Doe",
      "phone": "9911002211", // optional
      "full_address": "123 Main St, City",
      "dob": "01-01-1990",
      "registered_date": "01-01-2025",
      "tax_number": "ABCDE1234F", // optional
      "document_type": "AADHAAR",
      "document_front_image_url": "https://...",
      "document_back_image_url": "https://...",
      "document_details": {
        "document_number": "123456789012",
        "additional_data": {}
      },
      "selfie_url": "https://...",
      "selfie_verification_status": true,
      "additional_info": {
        "income_range": "<10L",
        "profession": "Engineer"
      }
    }
    ```
  </Tab>

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

Key fields:

* `customer_id`: ID received from Step 1
* `full_address`: Complete residential address
* `dob`: Date of birth (format: DD-MM-YYYY)
* `registered_date`: Date the user registered with the centralized exchange
* `tax_number`: Customer's tax number
* `document_type`: Type of ID document submitted
* `document_front_image_url` & `document_back_image_url`: Secure URLs to the uploaded document images
* `document_number`: Document number for the chosen document type (e.g. file number for Passport)
* `selfie_url`: Secure URL to the uploaded selfie
* `selfie_verification_status`: Whether the selfie passed verification
* `additional_info`: Additional fields required for KYC (e.g. `income_range`, `profession`)

<Tip>
  Use a secure file upload service to store document images and provide the URLs to the API. Never send document images as base64 strings.
</Tip>

<Info>
  Each customer gets 3 KYC attempts. If all three fail, the customer is blocked and must be resolved manually.
</Info>

### Verification process

After KYC submission, we run three checks in sequence:

#### 1. Document verification

We validate the submitted `document_number` (e.g. Passport file number) against official data sources and check:

* Document details match what was provided
* Document is not expired
* Document is not forged

If all checks pass, document verification completes and we proceed to tax verification.

If it fails, the KYC status moves to `FAILED` with reason `DOCUMENT_VERIFICATION_FAILED`.

#### 2. Tax verification

We validate the submitted `tax_number` (e.g., PAN) against official data sources and check:

* Tax number is valid and exists
* Tax number belongs to an individual
* Name and DOB in the API match records from official data sources

If all checks pass, tax verification completes and we proceed to additional information verification.

If it fails, the KYC status moves to `FAILED` with reason `TAX_VERIFICATION_FAILED`.

#### 3. Additional information verification

The `additional_info` fields are dynamic and depend on your organization's configuration, as returned by the [/kyc/configuration/{customer_id}](/api-reference-exchange/endpoint/kyc/configuration-\{customer_id}) API.

Some fields may require verification checks based on your configuration.

* If those checks pass, verification succeeds.
* If any required field fails, the KYC status moves to `FAILED` with reason `ADDITIONAL_INFO_VERIFICATION_FAILED`.

If no checks apply, this step completes automatically.

### Track verification status

After submitting KYC data, verification typically completes within 60 seconds. In exceptional cases, it can take up to 24 hours.

<Note>
  Most verifications complete within 60 seconds. In exceptional cases, it can take up to 24 hours. Set expectations with your users accordingly.
</Note>

#### Webhooks (recommended)

Configure a webhook endpoint to receive real-time KYC 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 periodically:

<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,
          "non_residence_status": false,
          "residence_alpha_3_country_code": null
      }
    }
    ```
  </Tab>
</Tabs>

<Tip>
  Poll no more than once every 60 seconds to avoid rate limits.
</Tip>

### Handle verification issues

If verification fails, prompt the user to correct and resubmit.

#### Document verification failed

Re-upload clearer images using the document update API.

<Tabs>
  <Tab title="API Request">
    ```json theme={null}
    POST /kyc/update-document-info
    {
        "customer_id": "075986f3-282b-4555-bfcd-fad973e32596",
        "full_address": "123 Main St, Apt 4B, City",
        "phone": "9911002211",
        "document_type": "PASSPORT",
        "document_front_image_url": "https://...",
        "document_back_image_url": "https://...",
        "document_details": {
            "document_number": "123456789012",
            "additional_data": {}
        }
    }
    ```
  </Tab>

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

<Tip>
  Common verification failures include:

  * Blurry or illegible document images
  * Mismatched name between documents
  * Incorrect tax number format
  * Expired identification documents
</Tip>

#### Tax verification failed

Resubmit a corrected tax number:

<Tabs>
  <Tab title="API Request">
    ```json theme={null}
    POST /kyc/update-tax-info
    {
        "customer_id": "075986f3-282b-4555-bfcd-fad973e32596",
        "tax_number": "XYZAB1234C"
    }
    ```
  </Tab>

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

#### Additional information verification failed

Resubmit corrected additional info:

<Tabs>
  <Tab title="API Request">
    ```json theme={null}
    POST /kyc/update-additional-info
    {
        "customer_id": "075986f3-282b-4555-bfcd-fad973e32596",
        "additional_info": {}
    }
    ```
  </Tab>

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