NADRA Verisys Flutter

A Flutter package for integrating NADRA Verisys API for Pakistani CNIC verification, biometric validation, and KYC compliance. Perfect for fintech, banking, e-commerce, and any application requiring identity verification in Pakistan.

🚀 Features

• ✅ CNIC Verification: Verify Pakistani national identity cards with NADRA database
• 🔐 Biometric Verification: Support for fingerprint-based verification
• 📊 Transaction History: Track and retrieve verification history
• 🛡️ Type-Safe: Fully typed models with comprehensive error handling
• 🧪 Sandbox Support: Test your integration in sandbox environment
• ⚡ Async/Await: Modern async API with Future-based methods
• 🎯 Production Ready: Built with best practices and error handling
• 📝 Well Documented: Comprehensive documentation and examples

📦 Installation

Add this to your package's pubspec.yaml file:

dependencies:
  nadra_verisys_flutter: ^0.1.2

Then run:

flutter pub get

🔑 Prerequisites

Before using this package, you need:

1. NADRA Verisys API credentials (API Key and optionally API Secret)
2. Institutional Access: NADRA Verisys is available only to regulated entities (banks, fintech companies, government departments) through a formal agreement with NADRA
3. How to Get Access:
   • Contact NADRA headquarters directly for institutional Verisys API access
   • Submit your business proposal and compliance documentation
   • Complete the KYC and institutional verification process
   • Receive API credentials after contract approval
   • Official Contact: Visit NADRA Official Website or e-Sahulat Portal

Note: This package provides the technical integration layer. You must obtain Verisys access through official NADRA channels.

🎯 Quick Start

Basic CNIC Verification

import 'package:nadra_verisys_flutter/nadra_verisys_flutter.dart';

void main() async {
  // Initialize the client
  final client = VerisysClient(
    apiKey: 'your-api-key-here',
    useSandbox: true, // Use sandbox for testing
  );

  // Create verification request
  final request = VerificationRequest(
    cnicNumber: '1234567890123', // 13-digit CNIC without dashes
    fullName: 'Muhammad Ali',
    dateOfBirth: '1990-01-01',
  );

  try {
    // Verify CNIC
    final response = await client.verifyCnic(request);

    if (response.isVerified) {
      print('✅ Verification successful!');
      print('Name: ${response.citizenData?.fullName}');
      print('Father Name: ${response.citizenData?.fatherName}');
      print('DOB: ${response.citizenData?.dateOfBirth}');
    } else {
      print('❌ Verification failed: ${response.message}');
    }
  } on VerisysException catch (e) {
    print('Error: ${e.message}');
  }

  // Don't forget to dispose
  client.dispose();
}

📖 Usage Examples

1. CNIC Verification with Multiple Fields

final request = VerificationRequest(
  cnicNumber: '4210112345678',
  fullName: 'Ahmed Khan',
  dateOfBirth: '1985-05-15',
  contactNumber: '03001234567',
  issueDate: '2010-01-01',
);

final response = await client.verifyCnic(request);

if (response.isVerified) {
  // Access citizen data
  final data = response.citizenData!;
  print('CNIC: ${data.cnicNumber}');
  print('Name: ${data.fullName}');
  print('Gender: ${data.gender}');
  print('Address: ${data.presentAddress}');
}

2. Biometric Verification

// Verify with fingerprint
final response = await client.verifyWithBiometric(
  cnicNumber: '4210112345678',
  fingerprint: 'base64-encoded-fingerprint-data',
);

if (response.isVerified) {
  print('Biometric verification successful!');
}

3. Get Verification History

final response = await client.getVerificationHistory('transaction-id-123');

print('Transaction ID: ${response.transactionId}');
print('Verified at: ${response.verifiedAt}');
print('Status: ${response.status}');

4. Production Configuration

final client = VerisysClient(
  apiKey: 'your-production-api-key',
  apiSecret: 'your-api-secret', // Optional
  useSandbox: false, // Production mode
  timeout: Duration(seconds: 30),
);

5. Custom Base URL

final client = VerisysClient(
  apiKey: 'your-api-key',
  baseUrl: 'https://custom.api.url/api', // Custom API endpoint
);

🔍 API Reference

VerisysClient

Main client for interacting with NADRA Verisys API.

Constructor Parameters

Parameter	Type	Required	Description
apiKey	String	Yes	Your NADRA Verisys API key
apiSecret	String	No	API secret (if required)
baseUrl	String	No	Custom API base URL
useSandbox	bool	No	Use sandbox environment (default: false)
timeout	Duration	No	Request timeout (default: 30s)

Methods

verifyCnic(VerificationRequest request)

Verifies a CNIC with NADRA database.

Returns: Future<VerificationResponse>

Throws: VerisysException on error

verifyWithBiometric({required String cnicNumber, required String fingerprint})

Verifies CNIC with biometric data.

Returns: Future<VerificationResponse>

getVerificationHistory(String transactionId)

Gets verification history for a transaction.

Returns: Future<VerificationResponse>

dispose()

Closes the HTTP client. Call this when you're done.

VerificationRequest

Request model for CNIC verification.

VerificationRequest({
  required String cnicNumber,    // 13-digit CNIC
  String? fullName,              // Full name
  String? dateOfBirth,           // YYYY-MM-DD format
  String? contactNumber,         // Phone number
  String? issueDate,             // CNIC issue date
})

Properties:

• isValidCnic: Validates CNIC format
• formattedCnic: Returns CNIC with dashes (xxxxx-xxxxxxx-x)

VerificationResponse

Response model containing verification results.

VerificationResponse({
  required VerificationStatus status,
  required String message,
  CitizenData? citizenData,
  String? transactionId,
  DateTime? verifiedAt,
  String? errorDetails,
})

Properties:

• isVerified: Returns true if verification was successful
• status: Verification status enum
• citizenData: Citizen information (if verified)

VerificationStatus

Enum representing verification status:

• VerificationStatus.verified - Verification successful
• VerificationStatus.failed - Verification failed
• VerificationStatus.notFound - CNIC not found
• VerificationStatus.error - API error
• VerificationStatus.pending - Pending verification

CitizenData

Citizen information from NADRA database.

CitizenData({
  required String cnicNumber,
  required String fullName,
  String? fatherName,
  String? dateOfBirth,
  String? gender,
  String? issueDate,
  String? expiryDate,
  String? presentAddress,
  String? permanentAddress,
  String? photo,  // Base64 encoded
})

VerisysException

Custom exception for API errors.

VerisysException({
  required String message,
  int? statusCode,
  dynamic originalError,
})

⚠️ Error Handling

The package throws VerisysException for various error scenarios:

try {
  final response = await client.verifyCnic(request);
} on VerisysException catch (e) {
  if (e.statusCode == 401) {
    print('Authentication failed: ${e.message}');
  } else if (e.statusCode == 429) {
    print('Rate limit exceeded: ${e.message}');
  } else {
    print('Error: ${e.message}');
  }
}

Common Error Codes

Status Code	Description
401	Authentication failed - Check API credentials
403	Access forbidden - Check API permissions
429	Rate limit exceeded - Try again later
500+	Server error - Try again later

🧪 Testing

Sandbox Environment

NADRA provides sandbox credentials to approved institutional clients for testing purposes. Use sandbox mode once you receive test credentials:

final client = VerisysClient(
  apiKey: 'your-sandbox-api-key', // Provided by NADRA
  useSandbox: true,
);

Important: Sandbox access and test credentials are provided by NADRA as part of the institutional onboarding process. Contact NADRA to receive your sandbox environment credentials.

Test Data

NADRA will provide you with test CNICs and expected responses for sandbox testing. Typical test scenarios include:

• Valid CNIC verification (successful match)
• Invalid CNIC format (validation error)
• CNIC not found (not in database)
• Mismatched information (verification failure)

Note: The actual test CNICs and their expected behaviors will be documented in your NADRA API access agreement.

📱 Platform Support

• ✅ Android
• ✅ iOS
• ✅ Web
• ✅ Windows
• ✅ macOS
• ✅ Linux

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• NADRA for providing the Verisys API
• Flutter community for awesome packages and support

📞 Support

For issues, questions, or contributions:

• 🐛 Report an issue
• 💬 Discussions
• 📧 Email: contact@ishaquehassan.com

🔗 Related Packages

• pakistan_payments_unified - Pakistani payment gateways
• shared_preferences - Local data storage

⚖️ Disclaimer

Important Notice:

• This is an unofficial package and is not affiliated with or endorsed by NADRA
• NADRA Verisys is a restricted service available only to regulated institutional clients (banks, fintech companies, government entities)
• You must obtain official API access from NADRA through their institutional onboarding process before using this package
• This package provides the technical integration layer only - it does not grant API access
• Use at your own risk and ensure full compliance with:
  • NADRA's terms of service and API usage policies
  • Pakistani data protection laws and regulations
  • Financial services regulations (if applicable to your use case)

For NADRA Verisys Access: Contact NADRA directly through their official channels at www.nadra.gov.pk

🌟 Show Your Support

If this package helped you, please give it a ⭐️ on GitHub!

---

Made with ❤️ by Ishaque Hassan