GuidesAPI ReferenceSDKsChangelog

KYC Sharing

Overview

KYC Sharing is an integration model that enables businesses to conduct KYC (Know Your Customer) verification independently and transmit the verified user data to DollarPe via API. Rather than utilizing DollarPe’s SDK to manage the full verification workflow, businesses maintain control over the identity verification process and provide only the necessary information for compliance integration.

This model is ideal for organizations with established KYC frameworks, offering a seamless way to connect with DollarPe without altering existing compliance operations.

By using KYC Sharing, you retain full control over the user experience while still ensuring compliance with DollarPe’s verification standards and regulatory requirements.

Customer Journey in KYC Sharing Flow

The diagram below outlines the end-to-end journey for a customer when using the KYC Sharing method. It covers every major step — from creating a customer profile to completing KYC and becoming eligible for transactions on DollarPe.

Process Flow Diagram

Processing Time: KYC verification typically takes 60 seconds to 120 minutes to complete. Design your user experience accordingly.

Submitting KYC Information

Fetching KYC Configuration

Once the customer profile is created, you can fetch the KYC configuration to understand the "document_type"(s) supported and the "additional_info" required for KYC using the /kyc/configuration/{customer_id} endpoint.

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: The options that are supported as "document_type" in /kyc/add-kyc-data endpoint
  • additional_info_required: Contains details about "additional_info" required in /kyc/add-kyc-data endpoint
    • options: Options for {field_name}
    • rules: Consists "type" (anyOf, allOf) and the "min_required" field to indicate the minimum number of fields that should be included in the "additional_info" of /kyc/add-kyc-data endpoint
    • {field_name}: Contains "type" for the field (string, url) and "required" field to indicate if that specific field in required in "additional_info" of /kyc/add-kyc-data endpoint

Adding KYC Data

Based on the KYC configuration, collect and submit their KYC details using the /kyc/add-kyc-data API.

Document Requirements:

  • Clear, high-resolution images
  • All document text must be legible
  • Supported document types: AADHAAR, PASSPORT, VOTER_ID, DRIVING_LICENSE
  • Make sure the customer's face is clearly visible in photo ID
POST /kyc/add-kyc-data
{
  "customer_id": "075986f3-282b-4555-bfcd-fad973e32596",
  "full_name": "John Doe",
  "phone": "9911002211",
  "full_address": "123 Main St, City",
  "dob": "01-01-1990",
  "registered_date": "01-01-2025",
  "tax_number": "ABCDE1234F",
  "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 on which the user registered with centralized exchange
  • tax_number: Tax number of the customer
  • document_type: Type of ID document submitted
  • document_front_image_url & document_back_image_url: Secure URLs to uploaded document images
  • document_number: Document number based on document type (e.g. File number for Passport)
  • selfie_url: Secure URL to uploaded selfie image
  • selfie_verification_status: Status of the selfie verification
  • additional_info: Additional Information required for KYC (e.g. "income_range" and "profession")

For best results, use a secure file upload service to store document images and provide the URLs to our API. Never send document images as base64 strings.

Each customer has 3 KYC attempts. This means that if the KYC fails 3 times, the customer will be blocked and resolved manually.

Verification Process

After KYC submission, we perform three core verification checks:

1. Document Verification

We validate the submitted document_number (e.g. Passport File Number, etc.) against official data sources and check -

  • The details in document matches with the details provided
  • The documents are not expired and valid
  • The document is not forged

If all the checks are passed, we mark the Document Verification as completed and proceed with the Tax verification.

In case of failure, the KYC status moves to FAILED with failure reason of DOCUMENT_VERIFICATION_FAILED

2. Tax Verification

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

  • If the Tax number is valid and existing
  • If the Tax number belongs to an individual user
  • If the Name and DOB provided in the API matches with the Name and DOB fetched from official data sources

If all the checks are passed, we mark the Tax Verification as completed and proceed with the additional information verification.

In case of failure, the KYC status moves to FAILED with failure reason of 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.

Some fields may require verification checks based on your configuration.

  • If such fields are configured and verified successfully, the verification passes.
  • If the verification checks fail for any of the required fields, the KYC status moves to FAILED with failure reason of ADDITIONAL_INFO_VERIFICATION_FAILED.

If no checks are applicable, this step is marked as complete automatically.

Track Verification Status

After submitting KYC data, our system begins the verification process, typically completing within 60 seconds. In exceptional cases, it could take up to 24 hours.

Verification Timeframe: Most verifications complete within 60 seconds. In exceptional cases, it could take up to 24 hours. You should communicate this expected timeline to your users to set proper expectations.

Option A: Webhook Integration (Recommended)

Webhooks provide real-time updates about KYC status changes. Configure your webhook endpoint to receive these notifications:

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

Option B: Status Polling

If webhooks aren't feasible, you can periodically check the status using the customer endpoint:

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

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

Handle Verification Issues

If verification fails, your system should help users correct and resubmit the problematic data.

Scenario A: Document Verification Failed

Use the document update API to re-upload clearer and correct images.

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

Scenario B: Tax Verification Failed

Use the following API to resubmit a corrected tax number:

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

Scenario C: Additional Information Verification Failed

Use the following API to resubmit a corrected additional information:

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