Add KYC to Your App

Integrate identity resolution into a Next.js application.

This guide walks through adding identity verification (KYC) to a Next.js application using the PlatformXe SDK.

Prerequisites

• A PlatformXe account with an API key that has identity scopes
• A Next.js 14+ application

Step 1: Install the SDK

npm install @caldera/platformxe-sdk

Step 2: Configure the client

// lib/platformxe.ts
import { PlatformXeClient } from '@caldera/platformxe-sdk';

export const px = new PlatformXeClient({
  apiKey: process.env.PLATFORMXE_API_KEY!,
});

Step 3: Create a verification API route

// app/api/verify-identity/route.ts
import { NextResponse } from 'next/server';
import { px } from '@/lib/platformxe';

export async function POST(req: Request) {
  const { bvn, nin, firstName, lastName, dateOfBirth, consentGiven } = await req.json();

  // Always require explicit consent before identity lookups
  if (!consentGiven) {
    return NextResponse.json(
      { success: false, error: { code: 'CONSENT_REQUIRED', message: 'User consent is required' } },
      { status: 400 },
    );
  }

  const result = await px.identity.resolve({
    bvn,
    nin,
    phone: undefined, // Only pass identifiers the user provided
  });

  // Mask sensitive fields before returning to the client
  return NextResponse.json({
    success: true,
    data: {
      verified: result.data.matchScore > 0.8,
      matchScore: result.data.matchScore,
      firstName: result.data.firstName,
      lastName: maskString(result.data.lastName),
    },
  });
}

function maskString(str: string): string {
  if (str.length <= 2) return '**';
  return str[0] + '*'.repeat(str.length - 2) + str[str.length - 1];
}

Step 4: Build the consent form

// components/kyc-form.tsx
'use client';
import { useState } from 'react';

export function KycForm() {
  const [consent, setConsent] = useState(false);
  const [bvn, setBvn] = useState('');
  const [result, setResult] = useState(null);

  async function handleSubmit(e: React.FormEvent) {
    e.preventDefault();
    const res = await fetch('/api/verify-identity', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ bvn, consentGiven: consent }),
    });
    setResult(await res.json());
  }

  return (
    <form onSubmit={handleSubmit}>
      <input
        type="text"
        value={bvn}
        onChange={e => setBvn(e.target.value)}
        placeholder="Enter BVN"
      />
      <label>
        <input
          type="checkbox"
          checked={consent}
          onChange={e => setConsent(e.target.checked)}
        />
        I consent to identity verification
      </label>
      <button type="submit" disabled={!consent}>Verify</button>
    </form>
  );
}

Step 5: Handle PII responsibly

Best practices:

• Always require explicit user consent before calling identity endpoints
• Mask PII in UI (show only first/last characters)
• Do not log full identity numbers in application logs
• Store only the verification status and reference ID
• Follow NDPR (Nigeria Data Protection Regulation) guidelines