GuidesAPI ReferenceSDKsChangelog

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:

Integration at a Glance

The KYC integration follows these main steps:

  1. Create a customer profile
  2. Fetch Generate KYC Link. User submits their KYC through the link and are redirected back to the URL provided
  3. Monitor verification status (usually completed within 60 seconds.)
  4. Add bank account details once verified
  5. Whitelist wallets to use in orders
  6. 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.

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

{
  "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": "+619911002211",
      "country": "AUS",
      "type": "INDIVIDUAL",
      "status": "UNVERIFIED"
  }
}

Key Fields:

  • client_reference_id: Unique reference ID generated by your system (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., "AUS" for Australia)

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

Step 2: Generating KYC Link & Submitting KYC

Generating KYC Link

Once the customer profile is created, you can generate and fetch the KYC link using the /kyc/generate-kyc-link endpoint.

POST /kyc/generate-kyc-link
{
  "customer_id": "075986f3-282b-4555-bfcd-fad973e32596",
  "redirect_url": "https://dollarpe.xyz"
}

{
  "status": true,
  "message": "Success",
  "data": {
    "customer_id": "075986f3-282b-4555-bfcd-fad973e32596",
    "url": "https://dollarpe.xyz/link/to/submit/kyc"
  }
}

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": "DOCUMENT_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: 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",
  "pay_id": "email@dollarpe.xyz",
  "pay_id_type": "EMAIL"
}

{
  "status": true,
  "message": "Success",
  "data": {
    "id": "4e6f1b20-a73c-11ec-b909-0242ac120002",
    "customer_id": "075986f3-282b-4555-bfcd-fad973e32596",
    "pay_id": "email@dollarpe.xyz",
    "pay_id_type": "EMAIL",
    "bank_account_status": "VERIFIED"
  }
}

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

Step 5: Whitelisting wallets

Before placing orders, the customer needs to whitelist their wallet address.

POST /wallet/add
{
  "customer_id": "075986f3-282b-4555-bfcd-fad973e32596",
  "wallet_address": "0x1234567890123456789012345678901234567890"
}

{
  "status": true,
  "message": "Success",
  "data": {
      "id": "4e6f1b20-a73c-11ec-b909-0242ac120002",
      "customer_id": "075986f3-282b-4555-bfcd-fad973e32596",
      "wallet_address": "0x1234567890123456789012345678901234567890",
      "wallet_status": "ACTIVE",
      "failure_reason": "null"
  }
}

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:

  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:

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.