porkate-valid8-identitypass

IdentityPass adapter for the Valid8 KYC/KYB verification framework. Provides Nigerian identity verification services including NIN, BVN, CAC, and more.

📚 Documentation

📖 View Full API Documentation - Complete API reference with all services, methods, and examples.

For detailed service documentation, see:

• IdentityPassAdapter
• IdentityPassCompositeAdapter
• All service classes (NIN, BVN, CAC, etc.)

Installation

npm install porkate-valid8-identitypass porkate-valid8
# or
yarn add porkate-valid8-identitypass porkate-valid8
# or
pnpm add porkate-valid8-identitypass porkate-valid8

Features

• Specialized Services: Dedicated service classes for each verification type
• Type-Safe: Full TypeScript support with strongly-typed requests and responses
• Multiple Verification Methods: Support for basic and advanced verification methods
• Face Matching: Face verification for NIN, BVN, Passport, and Driver's License
• Metadata Access: Original IdentityPass response available via meta field
• Backward Compatible: Legacy adapter still supported

Supported Verifications

• ✅ NIN (National Identification Number): Basic, With Face, Slip, Virtual NIN
• ✅ BVN (Bank Verification Number): Basic, Advance, With Face, By Phone Number
• ✅ CAC (Corporate Affairs Commission): Basic, Advance, Company Search by Name/Person/RC Number
• ✅ International Passport: Basic, V2, Image, With Face
• ✅ Driver's License: Basic, Advance, Image, With Face, V2
• ✅ Phone Number: Basic, Advance
• ✅ Bank Account: Basic, Advance, Comparison, List Bank Codes
• ✅ Vehicle: Plate Number, VIN/Chassis
• ✅ Tax: TIN, Stamp Duty
• ✅ Voter's Card: Basic verification
• ✅ Credit Bureau: Consumer (Basic/Advance), Commercial (Basic/Advance)
• ✅ Others: Address, NYSC, Insurance, National ID, WAEC, Documents (with/without Face)

Quick Start

Modern Approach (Recommended)

import { IdentityPassCompositeAdapter } from 'porkate-valid8-identitypass';

const adapter = new IdentityPassCompositeAdapter({
  apiKey: process.env.IDENTITY_PASS_API_KEY,
  appId: process.env.IDENTITY_PASS_APP_ID,
  baseUrl: 'https://api.myidentitypass.com', // optional
  timeout: 30000, // optional, default 30s
});

// Check if adapter is ready
if (!adapter.isReady()) {
  throw new Error('Adapter not configured properly');
}

// Get NIN service
const ninService = adapter.getNINService();
if (ninService) {
  // Basic NIN verification
  const result = await ninService.verifyNIN({
    nin: '12345678901',
    firstName: 'John',
    lastName: 'Doe',
    dateOfBirth: '1990-01-01',
  });

  if (result.success) {
    console.log('NIN verified:', result.data);
    console.log('Original response:', result.meta);
  } else {
    console.error('Verification failed:', result.error);
  }
}

Legacy Approach (Still Supported)

import { IdentityPassAdapter } from 'porkate-valid8-identitypass';

const adapter = new IdentityPassAdapter({
  apiKey: process.env.IDENTITY_PASS_API_KEY,
  appId: process.env.IDENTITY_PASS_APP_ID,
});

const result = await adapter.verifyNIN({
  nin: '12345678901',
  firstName: 'John',
  lastName: 'Doe',
});

console.log(result.success);
console.log(result.data);
console.log(result.meta); // Now includes original response

Usage Examples

NIN Verification

Basic NIN Verification

const ninService = adapter.getNINService();
const result = await ninService.verifyNIN({
  nin: '12345678901',
  firstName: 'John',
  lastName: 'Doe',
  dateOfBirth: '1990-01-01',
});

NIN with Face Matching

if (ninService.verifyNINWithFace) {
  const result = await ninService.verifyNINWithFace({
    nin: '12345678901',
    firstName: 'John',
    lastName: 'Doe',
    image: 'base64-encoded-face-image',
  });
}

NIN Slip Verification

if (ninService.verifyNINSlip) {
  const result = await ninService.verifyNINSlip({
    nin: '12345678901',
    slipNumber: 'SLIP123456',
  });
}

Virtual NIN Verification

if (ninService.verifyVirtualNIN) {
  const result = await ninService.verifyVirtualNIN({
    virtualNin: 'VNIN123456789',
    firstName: 'John',
    lastName: 'Doe',
  });
}

BVN Verification

Basic BVN Verification

const bvnService = adapter.getBVNService();
const result = await bvnService.verifyBVN({
  bvn: '12345678901',
  firstName: 'John',
  lastName: 'Doe',
  dateOfBirth: '1990-01-01',
});

BVN Advance Verification

if (bvnService.verifyBVNAdvance) {
  const result = await bvnService.verifyBVNAdvance({
    bvn: '12345678901',
    includeHistory: true,
  });
}

BVN with Face Matching

if (bvnService.verifyBVNWithFace) {
  const result = await bvnService.verifyBVNWithFace({
    bvn: '12345678901',
    image: 'base64-encoded-face-image',
  });
}

Get BVN by Phone Number

if (bvnService.getBVNByPhoneNumber) {
  const result = await bvnService.getBVNByPhoneNumber({
    phoneNumber: '+2348012345678',
  });
}

CAC (Company) Verification

Basic CAC Verification

const cacService = adapter.getCACService();
if (cacService) {
  const result = await cacService.verifyCAC({
    rcNumber: 'RC1234567',
    // or use bnNumber or companyName
  });
}

Advanced CAC with Directors and Shareholders

if (cacService?.verifyCACAdvance) {
  const result = await cacService.verifyCACAdvance({
    rcNumber: 'RC1234567',
    includeDirectors: true,
    includeShareholdings: true,
  });
}

Company Search by Name

if (cacService?.searchCompanyByName) {
  const result = await cacService.searchCompanyByName({
    companyName: 'Example Corp',
  });
}

Vehicle Verification

const vehicleService = adapter.getVehicleService();
if (vehicleService) {
  // By plate number
  const result = await vehicleService.verifyPlateNumber({
    plateNumber: 'ABC123XY',
  });
  
  // By VIN/Chassis
  const result2 = await vehicleService.verifyVINChasis({
    vinNumber: '1HGBH41JXMN109186',
  });
}

Driver's License Verification

const dlService = adapter.getDriversLicenseService();
if (dlService) {
  // Basic verification
  const result = await dlService.verifyDriversLicense({
    licenseNumber: 'FKJ1234567',
    firstName: 'John',
    lastName: 'Doe',
  });
  
  // With face matching
  if (dlService.verifyDriversLicenseWithFace) {
    const result2 = await dlService.verifyDriversLicenseWithFace({
      licenseNumber: 'FKJ1234567',
      image: 'base64-encoded-face-image',
    });
  }
}

Passport Verification

const passportService = adapter.getPassportService();
if (passportService) {
  // Basic passport verification
  const result = await passportService.verifyPassport({
    passportNumber: 'A12345678',
    firstName: 'John',
    lastName: 'Doe',
  });
  
  // With face matching
  if (passportService.verifyPassportWithFace) {
    const result2 = await passportService.verifyPassportWithFace({
      passportNumber: 'A12345678',
      image: 'base64-encoded-face-image',
    });
  }
}

Phone Number Verification

const phoneService = adapter.getPhoneService();
if (phoneService) {
  // Basic verification
  const result = await phoneService.verifyPhoneNumber({
    phoneNumber: '+2348012345678',
  });
  
  // Advanced with carrier info
  if (phoneService.verifyPhoneNumberAdvance) {
    const result2 = await phoneService.verifyPhoneNumberAdvance({
      phoneNumber: '+2348012345678',
      includeCarrierInfo: true,
    });
  }
}

Bank Account Verification

const bankService = adapter.getBankAccountService();
if (bankService) {
  // Basic verification
  const result = await bankService.verifyBankAccount({
    accountNumber: '0123456789',
    bankCode: '058',
  });
  
  // Account comparison with name
  if (bankService.compareBankAccount) {
    const result2 = await bankService.compareBankAccount({
      accountNumber: '0123456789',
      bankCode: '058',
      firstName: 'John',
      lastName: 'Doe',
    });
  }
  
  // List available bank codes
  if (bankService.listBankCodes) {
    const banks = await bankService.listBankCodes();
  }
}

Tax Verification

const taxService = adapter.getTaxService();
if (taxService) {
  // TIN verification
  const result = await taxService.verifyTIN({
    tin: '12345678-0001',
    channel: 'online',
  });
  
  // Stamp duty verification
  if (taxService.verifyStampDuty) {
    const result2 = await taxService.verifyStampDuty({
      referenceNumber: 'SD123456789',
    });
  }
}

Voter's Card Verification

const votersService = adapter.getVotersCardService();
if (votersService) {
  const result = await votersService.verifyVotersCard({
    vin: '90F5B12345678901',
    firstName: 'John',
    lastName: 'Doe',
    state: 'Lagos',
  });
}

Credit Bureau Verification

const creditService = adapter.getCreditBureauService();
if (creditService) {
  // Consumer credit - basic
  if (creditService.verifyCreditBureauConsumerBasic) {
    const result = await creditService.verifyCreditBureauConsumerBasic({
      bvn: '12345678901',
      phoneNumber: '+2348012345678',
    });
  }
  
  // Consumer credit - advanced
  if (creditService.verifyCreditBureauConsumerAdvance) {
    const result2 = await creditService.verifyCreditBureauConsumerAdvance({
      bvn: '12345678901',
      includeHistory: true,
    });
  }
  
  // Commercial credit - basic
  if (creditService.verifyCreditBureauCommercialBasic) {
    const result3 = await creditService.verifyCreditBureauCommercialBasic({
      rcNumber: 'RC1234567',
    });
  }
}

Other Verification Services

const otherService = adapter.getOtherService();
if (otherService) {
  // Address verification
  if (otherService.verifyAddress) {
    const result = await otherService.verifyAddress({
      address: '123 Main St, Lagos',
      state: 'Lagos',
    });
  }
  
  // NYSC verification
  if (otherService.verifyNYSC) {
    const result2 = await otherService.verifyNYSC({
      certificateNumber: 'NYSC/12345/2020',
      firstName: 'John',
      lastName: 'Doe',
    });
  }
  
  // WAEC verification
  if (otherService.verifyWAEC) {
    const result3 = await otherService.verifyWAEC({
      examNumber: '1234567890',
      examYear: '2020',
    });
  }
  
  // Insurance policy verification
  if (otherService.verifyInsurancePolicy) {
    const result4 = await otherService.verifyInsurancePolicy({
      policyNumber: 'POL123456789',
    });
  }
  
  // Document verification with face
  if (otherService.verifyDocumentWithFace) {
    const result5 = await otherService.verifyDocumentWithFace({
      documentType: 'national_id',
      documentNumber: 'ID123456789',
      image: 'base64-encoded-document-image',
      faceImage: 'base64-encoded-face-image',
    });
  }
}

## Response Structure

All verification methods return a standardized response:

```typescript
interface VerificationResponse<T, M> {
  success: boolean;              // Verification success status
  data?: T;                      // Typed verification data
  message?: string;              // Human-readable message
  error?: string;                // Error message if failed
  provider: string;              // "identitypass"
  timestamp: Date;               // Response timestamp
  meta?: M;                      // Original IdentityPass API response
}

Example Response

{
  success: true,
  data: {
    nin: '12345678901',
    firstName: 'John',
    lastName: 'Doe',
    middleName: 'Smith',
    dateOfBirth: '1990-01-01',
    gender: 'Male',
    phoneNumber: '+2348012345678',
    address: '123 Main St, Lagos',
    photo: 'base64-encoded-photo',
    stateOfOrigin: 'Lagos',
    lga: 'Lagos Island',
    // ... other fields
  },
  message: 'Verification successful',
  provider: 'identitypass',
  timestamp: new Date('2024-01-01T00:00:00Z'),
  meta: {
    // Original IdentityPass API response
    status: true,
    detail: 'Verification successful',
    response_code: '00',
    verification: {
      nin: '12345678901',
      firstname: 'John',
      lastname: 'Doe',
      // ... all original fields from IdentityPass
    }
  }
}

Configuration

interface IdentityPassConfig {
  apiKey: string;                                    // Required: Your IdentityPass API key (x-api-key header)
  appId: string;                                     // Required: Your IdentityPass App ID (app-id header)
  baseUrl?: string;                                 // Optional: Default 'https://api.myidentitypass.com'
  timeout?: number;                                 // Optional: Request timeout in ms, default 30000
}

Error Handling

try {
  const ninService = adapter.getNINService();
  
  if (!ninService) {
    throw new Error('NIN verification service not available');
  }

  const result = await ninService.verifyNIN({
    nin: '12345678901',
  });

  if (!result.success) {
    console.error('Verification failed:', result.error);
    console.error('Meta data:', result.meta);
  }
} catch (error) {
  console.error('Request error:', error.message);
}

Checking Method Availability

const ninService = adapter.getNINService();

if (ninService) {
  // Basic verification always available
  await ninService.verifyNIN({...});

  // Check optional methods
  if (ninService.verifyNINWithFace) {
    await ninService.verifyNINWithFace({...});
  }

  if (ninService.verifyNINSlip) {
    await ninService.verifyNINSlip({...});
  }
}

Integration with Verification Manager

import { VerificationManager } from 'porkate-valid8';
import { IdentityPassAdapter } from 'porkate-valid8-identitypass';

const manager = new VerificationManager({
  defaultAdapter: 'identitypass',
  enableFallback: true,
  adapters: [
    {
      name: 'identitypass',
      enabled: true,
      priority: 1,
      config: {
        apiKey: process.env.IDENTITY_PASS_API_KEY,
        appId: process.env.IDENTITY_PASS_APP_ID,
      },
    },
  ],
});

manager.registerFactory('identitypass', (config) => {
  return new IdentityPassAdapter(config);
});

const adapter = manager.getDefaultAdapter();
const result = await adapter.verifyNIN({...});

Best Practices

1. Environment Variables: Store API credentials in environment variables

   const apiKey = process.env.IDENTITY_PASS_API_KEY;
   const appId = process.env.IDENTITY_PASS_APP_ID;
   if (!apiKey || !appId) {
     throw new Error('IDENTITY_PASS_API_KEY and IDENTITY_PASS_APP_ID must be set');
   }

2. Check Service Availability: Always verify service exists before use

   const service = adapter.getNINService();
   if (!service) {
     throw new Error('Service not available');
   }

3. Handle Optional Methods: Use optional chaining or checks

   if (service.verifyNINWithFace) {
     await service.verifyNINWithFace({...});
   }

4. Access Original Response: Use meta field for adapter-specific data

   console.log(result.meta.response_code); // IdentityPass response code

5. Error Handling: Always handle both success and error cases

   if (result.success) {
     // Handle success
   } else {
     // Handle failure
     console.error(result.error);
   }

TypeScript Support

Full TypeScript support with comprehensive type definitions:

import type {
  IdentityPassAdapter,
  IdentityPassCompositeAdapter,
  IdentityPassConfig,
  IdentityPassVerificationResponse,
} from 'porkate-valid8-identitypass';

import type {
  NINVerificationRequest,
  NINVerificationData,
  BVNVerificationRequest,
  BVNVerificationData,
  VerificationResponse,
} from 'porkate-valid8';

Testing

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Generate coverage report
npm run test:coverage

API Documentation

For detailed IdentityPass API documentation, visit:

• IdentityPass Documentation

Architecture

For detailed information about the specialized services architecture, see ARCHITECTURE.md.

Contributing

Contributions are welcome! To add new verification services:

1. Create interface in porkate-valid8/interfaces/verification-services/
2. Implement service class extending BaseIdentityPassService
3. Add getter method in IdentityPassCompositeAdapter
4. Update documentation
5. Add tests

License

MIT

Support

• GitHub Issues: PorkAte-Valid8
• Documentation: ARCHITECTURE.md

Related Packages

• porkate-valid8 - Core verification manager
• porkate-valid8-dashboard - Monitoring dashboard
• porkate-valid8-nest - NestJS integration