KYC sharing - DollarPe

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

Verification typically takes 60 seconds to 2 hours. Design your user experience accordingly.

Submitting KYC Information

Fetching KYC configuration

Fetch the KYC configuration to get supported document types and required additional fields using the /kyc/configuration/ endpoint.

API Request
Response

GET /kyc/configuration/{customer_id}

{
  "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
          }
      }
  }
}

Key fields:

supported_document_types: Valid values for document_type in /kyc/add-kyc-data
additional_info_required: Describes the additional_info fields required in /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.

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.

API Request
Response

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"
  }
}

{
  "status": true,
  "message": "Success",
  "data": {
      "customer_id": "075986f3-282b-4555-bfcd-fad973e32596",
      "status": "PROCESSING"
  }
}

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)

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

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

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/ 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.

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

Webhooks (recommended)

Configure a webhook endpoint to receive real-time KYC status updates:

// 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:

API Request
Response

GET /customer/{customer_id}

{
  "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
  }
}

Poll no more than once every 60 seconds to avoid rate limits.

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.

API Request
API Response

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": {}
    }
}

{
    "status": true,
    "message": "Success",
    "data": {
        "customer_id": "075986f3-282b-4555-bfcd-fad973e32596",
        "status": "PROCESSING"
    }
}

Common verification failures include:

Blurry or illegible document images
Mismatched name between documents
Incorrect tax number format
Expired identification documents

Tax verification failed

Resubmit a corrected tax number:

API Request
API Response

POST /kyc/update-tax-info
{
    "customer_id": "075986f3-282b-4555-bfcd-fad973e32596",
    "tax_number": "XYZAB1234C"
}

{
    "status": true,
    "message": "Success",
    "data": {
        "customer_id": "075986f3-282b-4555-bfcd-fad973e32596",
        "status": "PROCESSING"
    }
}

Additional information verification failed

Resubmit corrected additional info:

API Request
API Response

POST /kyc/update-additional-info
{
    "customer_id": "075986f3-282b-4555-bfcd-fad973e32596",
    "additional_info": {}
}

{
    "status": true,
    "message": "Success",
    "data": {
        "customer_id": "075986f3-282b-4555-bfcd-fad973e32596",
        "status": "PROCESSING"
    }
}

Documentation Index

​Customer journey

​Submitting KYC Information

​Fetching KYC configuration

​Adding KYC data

​Verification process

​1. Document verification

​2. Tax verification

​3. Additional information verification

​Track verification status

​Webhooks (recommended)

​Polling

​Handle verification issues

​Document verification failed

​Tax verification failed

​Additional information verification failed

Customer journey

Submitting KYC Information

Fetching KYC configuration

Adding KYC data

Verification process

1. Document verification

2. Tax verification

3. Additional information verification

Track verification status

Webhooks (recommended)

Polling

Handle verification issues

Document verification failed

Tax verification failed

Additional information verification failed