> ## 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 Integration Guide

<Highlight>
  # KYC Integration Guide
</Highlight>

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

<Note>
  **Before You Begin:**

  * Complete the [authentication setup](/guides/introduction) for API access
  * Set up your [webhook endpoint](/api-reference-exchange/endpoint/organizations/api-webhooks) to receive real-time KYC status updates
</Note>

## Integration at a Glance

The KYC integration follows these main steps:

1. [Create](/api-reference-exchange/endpoint/customer/create) a customer profile
2. Fetch [KYC Configuration](/api-reference-exchange/endpoint/kyc/configuration-\{customer_id})
3. [Submit](/api-reference-exchange/endpoint/kyc/add-kyc-data) their KYC documents and information
4. Monitor verification status (usually completed within 60 seconds.)
5. Handle any verification issues ([Document](/api-reference-exchange/endpoint/kyc/update-document-info), [Tax](/api-reference-exchange/endpoint/kyc/update-tax-info), [Additional Information](api-reference-exchange/endpoint/kyc/update-additional-info))
6. [Add bank account](/api-reference-exchange/endpoint/bank/create) details once verified
7. Begin transactions for [Payout](/api-reference-exchange/endpoint/payout/initiate) and [Payin](/api-reference-exchange/endpoint/payin/initiate)

## Visual Integration Flow

### Process Flow Diagram

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

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

<Tabs>
  <Tab title="API Request">
    ```javascript theme={null}
    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"
    }
    ```
  </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"
      }
    }
    ```
  </Tab>
</Tabs>

**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)

<Note>
  Save the returned `customer_id` as you'll need it for all subsequent API calls.
</Note>

### 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}](/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`: The options that are supported as "document\_type" in [/kyc/add-kyc-data](/api-reference-exchange/endpoint/kyc/add-kyc-data) endpoint
* `additional_info_required`: Contains details about "additional\_info" required in [/kyc/add-kyc-data](/api-reference-exchange/endpoint/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](/api-reference-exchange/endpoint/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](/api-reference-exchange/endpoint/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-reference-exchange/endpoint/kyc/add-kyc-data) API.

<Warning>
  **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
</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 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")

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

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

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

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

#### Option A: Webhook Integration (Recommended)

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

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

#### Option B: Status Polling

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

<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>
  If using the polling approach, we recommend checking no more frequently than once every 60 seconds to avoid API rate limits.
</Tip>

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

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

#### Scenario B: Tax Verification Failed

Use the following API to 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>

#### Scenario C: Additional Information Verification Failed

Use the following API to resubmit a corrected additional information:

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

### Step 5: Add Bank Account Details

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

<Tabs>
  <Tab title="API Request">
    ```javascript theme={null}
    POST /bank/add-account
    {
      "customer_id": "075986f3-282b-4555-bfcd-fad973e32596",
      "account_number": "123456789012",
      "ifsc": "ABC123456"
    }
    ```
  </Tab>

  <Tab title="Response">
    ```json theme={null}
    {
      "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"
      }
    }
    ```
  </Tab>
</Tabs>

<Note>
  Instead of "account\_number" and "ifsc", you can also pass "vpa" to add a UPI ID.
</Note>

### 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](/api-reference-exchange/integration-guides/payout-integration-guide))
* Process fiat-to-crypto conversions ([Payin](/api-reference-exchange/integration-guides/payin-integration-guide))

## Testing Your Integration

### Sandbox Environment

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

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

## Getting Help

If you encounter any issues with your KYC integration:

* Check our [API documentation](/api-reference-exchange) for detailed endpoint information
* Visit the [Troubleshooting Guide](/guides/faq) for common solutions
* Contact our [support team](mailto:support@dollarpe.xyz) with your customer\_id and transaction logs

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