KYC Integration Guide

What is KYC and Why It Matters

Know Your Customer (KYC) verification is an essential process that helps verify the identity of your users, prevent fraud, and comply with regulatory requirements. This guide will walk you through integrating DollarPe’s KYC system into your application, whether you’re a developer or a business owner.

Before You Begin:

Complete the authentication setup for API access
Set up your webhook endpoint to receive real-time KYC status updates

Integration at a Glance

The KYC integration follows these main steps:

Create a customer profile
Fetch KYC Configuration
Submit their KYC documents and information
Monitor verification status (usually completed within 60 seconds.)
Handle any verification issues (Document, Tax, Additional Information)
Add bank account details once verified
Begin transactions for Payout and Payin

Visual Integration Flow

Process Flow Diagram

Verification Timeframe: Most verifications are completed within 60 seconds. In exceptional cases, it could take up to 24 hours.. Communicate this timeline to users to manage expectations.

Step-by-Step Integration Guide

Step 1: Create a Customer Profile

First, register your customer in the system. This creates a unique customer ID that will be used throughout the KYC process.

API Request
Response

POST /customer/create
{
  "client_reference_id": "cus_12345abcde", // optional
  "full_name": "JOHN DOE",
  "email": "john@example.com",
  "phone": "9911002211", // optional
  "alpha_3_country_code": "IND"
}

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

Key Fields:

client_reference_id: Unique reference ID generated by your system (optional) (e.g. Your user ID)
full_name: Customer’s legal name
email: Valid email address
phone: Contact number
alpha_3_country_code: Country code of customer’s nationality (e.g., “IND” for India)

Save the returned customer_id as you’ll need it for all subsequent API calls.

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

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

Step 3: 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:

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

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

Step 4: 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.

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": "AADHAAR",
    "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:

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

Scenario C: Additional Information Verification Failed

Use the following API to resubmit a corrected additional information:

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

Step 5: Add Bank Account Details

Once KYC verification is successful, you can add the customer’s bank account:

API Request
Response

POST /bank/add-account
{
  "customer_id": "075986f3-282b-4555-bfcd-fad973e32596",
  "account_number": "123456789012",
  "ifsc": "ABC123456"
}

{
  "status": true,
  "message": "Success",
  "data": {
    "id": "4e6f1b20-a73c-11ec-b909-0242ac120002",
    "customer_id": "075986f3-282b-4555-bfcd-fad973e32596",
    "account_number": "123456789012",
    "ifsc_code": "ABC123456",
    "vpa": null,
    "bank_account_type": "ACCOUNT_DETAILS",
    "bank_account_status": "VERIFIED"
  }
}

Instead of “account_number” and “ifsc”, you can also pass “vpa” to add a UPI ID.

Step 6: Ready for Transactions

Once KYC is verified and bank details are added, the customer can start transacting. At this point, you can:

Process crypto-to-fiat conversions (Payout)
Process fiat-to-crypto conversions (Payin)

Testing Your Integration

Sandbox Environment

Before going live, test your integration thoroughly in our sandbox environment:

Use the base URL: https://sandbox.dollarpe.xyz
Create test customers on sandbox
Test both successful and failed verification scenarios

Getting Help

If you encounter any issues with your KYC integration:

Check our API documentation for detailed endpoint information
Visit the Troubleshooting Guide for common solutions
Contact our support team with your customer_id and transaction logs

Our support team is available 24/7 to help with integration issues. For urgent matters, use the in-app chat or call our technical support hotline.

Integration Guides

Customer

Payout (off-ramp)

Payin (on-ramp)

Webhook

Widget

KYC Integration Guide

What is KYC and Why It Matters

Integration at a Glance

Visual Integration Flow

Process Flow Diagram

Step-by-Step Integration Guide

Step 1: Create a Customer Profile

Step 2: Submitting KYC Information

Fetching KYC Configuration

Adding KYC Data

Step 3: Track Verification Status

Option A: Webhook Integration (Recommended)

Option B: Status Polling

Step 4: Handle Verification Issues

Scenario A: Document Verification Failed

Scenario B: Tax Verification Failed

Scenario C: Additional Information Verification Failed

Step 5: Add Bank Account Details

Step 6: Ready for Transactions

Testing Your Integration

Sandbox Environment

Getting Help

Integration Guides

Customer

Payout (off-ramp)

Payin (on-ramp)

Webhook

Widget

​What is KYC and Why It Matters

​Integration at a Glance

​Visual Integration Flow

​Process Flow Diagram

​Step-by-Step Integration Guide

​Step 1: Create a Customer Profile

​Step 2: Submitting KYC Information

​Fetching KYC Configuration

​Adding KYC Data

​Step 3: Track Verification Status

​Option A: Webhook Integration (Recommended)

​Option B: Status Polling

​Step 4: Handle Verification Issues

​Scenario A: Document Verification Failed

​Scenario B: Tax Verification Failed

​Scenario C: Additional Information Verification Failed

​Step 5: Add Bank Account Details

​Step 6: Ready for Transactions

​Testing Your Integration

​Sandbox Environment

​Getting Help

What is KYC and Why It Matters

Integration at a Glance

Visual Integration Flow

Process Flow Diagram

Step-by-Step Integration Guide

Step 1: Create a Customer Profile

Step 2: Submitting KYC Information

Fetching KYC Configuration

Adding KYC Data

Step 3: Track Verification Status

Option A: Webhook Integration (Recommended)

Option B: Status Polling

Step 4: Handle Verification Issues

Scenario A: Document Verification Failed

Scenario B: Tax Verification Failed

Scenario C: Additional Information Verification Failed

Step 5: Add Bank Account Details

Step 6: Ready for Transactions

Testing Your Integration

Sandbox Environment

Getting Help