On-Chain KYC

This guide provides the steps and instructions for integrating Privado ID-based KYC verification directly in your frontend application, utilizing the Privado ID verifier API at https://verifier-backend.privado.id.

Prerequisites

Before you begin integrating Privado ID verification, ensure you have the following:

  • A React-based frontend.

  • Frontend access to https://verifier-backend.privado.id for generating QR codes and checking the verification status.

  • The qrcode.react npm package for rendering QR codes.

Integration Steps

Step 1: Set up Frontend Components

The frontend will be responsible for interacting with users, displaying the QR code, and updating the verification status.

1.1 React Components

  • StatusCard: A component that shows the current KYC status (e.g., "Pending", "Verifying", "Approved", or "Failed").

  • QRCodeSection: Displays the QR code generated for the user to scan with their Privado ID wallet.

  • ActionButtons: Provides buttons like "Start KYC" and "Retry" to allow users to interact with the verification process.

// Example for displaying QR code and status
import React, { useState } from 'react';
import { handlePolygonVerification, pollVerificationStatus } from './api'; // Functions to initiate verification and poll status

const KYCPage = () => {
  const [status, setStatus] = useState('pending');
  const [qrCode, setQrCode] = useState(null);
  const [sessionID, setSessionID] = useState(null);

  const startVerification = async () => {
    const result = await handlePolygonVerification();
    setQrCode(result.qrCode);
    setSessionID(result.sessionID);
    setStatus('verifying');
    pollVerificationStatus(result.sessionID, setStatus); // Poll verification status
  };

  return (
    <div>
      <h1>Privado ID KYC Verification</h1>
      <LhStatusCard status={status} />
      {status === 'verifying' && <LhQRCodeSection qrCode={qrCode} />}
      <LhActionButtons onClick={startVerification} />
    </div>
  );
};

1.2 Handle Verification Requests

Use a function to send a POST request to the Privado ID API to generate the QR code.

// Function to handle verification request
export const handlePolygonVerification = async () => {
  const response = await fetch('https://verifier-backend.privado.id/sign-in', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      chainID: "1952959480", - Lumia Testnet
      scope: [
        {
          circuitId: "credentialAtomicQueryMTPV2",
          id: 1734435086,
          query: {
            allowedIssuers: ["*"],
            context: "https://raw.githubusercontent.com/shiva-decrypt/lumai-json/main/lumiav2.jsonld",
            type: "KYC",
            credentialSubject: {
              Kyc_Approved: { "$eq": true }
            }
          }
        }
      ],
      skipClaimRevocationCheck: false
    })
  });

  const data = await response.json();
  return {
    qrCode: data.qrCode,
    sessionID: data.sessionID,
  };
};

Explanation of the body Section in the Request

The body of the request is a JSON object sent to the Privado ID verifier backend. Here's a breakdown of its components:

1. chainID: "XXXXXXX"

  • Specifies the blockchain network used.

  • 1952959480 corresponds to the Lumia Testnet.

  • 994873017 corresponds to the Lumia Mainnet (Prism)

2. scope

  • Purpose: Defines the query parameters and the type of credential to verify.

  • Contains an array of query objects. Each query object includes:

    • circuitId: "credentialAtomicQueryMTPV2"

      • Specifies the type of cryptographic circuit used for verification.

      • In this case, it's credentialAtomicQueryMTPV2, which supports secure and private verification of claims.

    • id: 1734435086

      • A unique identifier for the query.

    • query: Describes the claim or condition to be checked.

      • allowedIssuers: ["*"]

        • Allows credentials from any issuer (*).

      • context:

        • A URL pointing to the JSON-LD schema defining the structure of the credential.

        • In this case, it links to a schema stored in a GitHub repository.

      • type: "KYC"

        • Specifies the type of credential being validated.

      • credentialSubject:

        • Defines the specific conditions the credential must meet.

        • In this example, Kyc_Approved: { "$eq": true } requires that the Kyc_Approved field in the credential is true.

3. skipClaimRevocationCheck: false

  • Ensures that the claim revocation status is verified.

  • If set to true, the verification would skip checking if the claim has been revoked, which might reduce security.

Possible Modifications

1. Customizing Allowed Issuers

  • Instead of allowing any issuer (allowedIssuers: ["*"]), you can specify trusted issuers. Example:

    Copy

    "allowedIssuers": ["did:polygon:abc123", "did:polygon:def456"]

2. Using a Custom Credential Type

  • Change the type from "KYC" to other credential types if needed. Ensure the schema in the context URL matches the new type.

3. Dynamic chainID Selection

  • If your application supports multiple networks, the chainID can be dynamically passed based on the selected environment (e.g., mainnet or testnet).

4. Revocation Check Skipping

  • For faster verification in non-critical use cases, set skipClaimRevocationCheck to true. However, this is not recommended for sensitive processes.

5. Adding Additional Query Conditions

  • You can validate more fields by adding them to the credentialSubject. Example:

    Copy

    "credentialSubject": {
  "Kyc_Approved": { "$eq": true },
  "Age": { "$gte": 18 }
}

    This ensures the user is at least 18 years old and has passed KYC.

Step 2: Poll Verification Status

After the QR code is generated, you need to periodically check the status of the verification to keep the user updated.

// Function to poll verification status
export const pollVerificationStatus = async (sessionID, setStatus) => {
  const response = await fetch(`https://verifier-backend.privado.id/status?sessionID=${sessionID}`);
  const data = await response.json();

  if (data.status === 'success') {
    setStatus('approved');
  } 

  // Poll every 5 seconds until verification is completed
  if (data.status !== 'approved' && data.status !== 'failed') {
    setTimeout(() => pollVerificationStatus(sessionID, setStatus), 5000);
  }
};

Step 3: Handle User Interaction

Users can interact with the system by clicking the "Start KYC" button to initiate the verification process and retry if needed.

Example UI Components

import { QRCodeSVG } from 'qrcode.react';

export const LhStatusCard = ({ status }) => {
  return (
    <div>
      <h2>Status: {status}</h2>
    </div>
  );
};

export const LhQRCodeSection = ({ qrCode }) => {
  return (
    <div>
    <QRCodeSVG
              value={qrCode}
              size={400}
              level="H"
              className="h-full w-full"
              includeMargin
              bgColor="#f3f4f6"
              fgColor="#4f46e5"
            />
    </div>
  );
};

export const LhActionButtons = ({ onClick }) => {
  return (
    <div>
      <button onClick={onClick}>Start KYC</button>
    </div>
  );
};

Final Steps

  1. Start the KYC Process:

    • The user clicks the “Start KYC” button, triggering the startVerification function.

    • A QR code will be displayed for the user to scan with their Polygon ID wallet.

  2. Track the Verification Status:

    • Once the user scans the QR code, the status will update to "Verifying."

    • The frontend will automatically poll the status every 5 seconds until the status is either "Approved" or "Failed."

  3. Handle Status Changes:

    • Upon successful verification, the status will update to "Approved".

    • If verification fails, the user can click “Retry” to attempt the process again.

Troubleshooting

  • Issue: QR code is not displayed.

    • Solution: Ensure that the API is returning a valid qrCode URL. Verify that your frontend is correctly displaying the image.

  • Issue: Verification fails.

    • Solution: Confirm that the user's Privado ID wallet app is properly configured and connected to the internet.

  • Issue: Status remains "Pending" for too long.

    • Solution: Ensure the sessionID is valid and being correctly used to check the verification status. You may also want to check for any issues with the Privado ID service.

Conclusion

By following this guide, you can integrate Privado ID verification directly into your frontend application, allowing users to verify their KYC status with ease. The process involves generating a QR code, tracking the status, and providing feedback to the user throughout the verification process.

PreviousWeb3 FunctionsNextOracles

Last updated