KYC Integration

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

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

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.

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/{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", // 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:

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.

<scalar-tab title="API Request">
```json
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": {}
    }
}
```
</scalar-tab> 
<scalar-tab title="API Response">
```json
{
    "status": true,
    "message": "Success",
    "data": {
        "customer_id": "075986f3-282b-4555-bfcd-fad973e32596",
        "status": "PROCESSING"
    }
}
```
</scalar-tab>

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:

<scalar-tab title="API Request">
```json
POST /kyc/update-tax-info
{
    "customer_id": "075986f3-282b-4555-bfcd-fad973e32596",
    "tax_number": "XYZAB1234C"
}
```
</scalar-tab> 
<scalar-tab title="API Response">
```json
{
    "status": true,
    "message": "Success",
    "data": {
        "customer_id": "075986f3-282b-4555-bfcd-fad973e32596",
        "status": "PROCESSING"
    }
}
```
</scalar-tab>

Scenario C: Additional Information Verification Failed

Use the following API to resubmit a corrected additional information:

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

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

</scalar-tab>

Step 5: Add Bank Account Details

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

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.