nadra_verisys_flutter 0.1.0

A Flutter package for integrating NADRA Verisys API for Pakistani CNIC verification, biometric validation, and KYC compliance. Perfect for fintech, banking, and identity verification apps.

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.0

Then run:

flutter pub get

🔑 Prerequisites

Before using this package, you need:

1. NADRA Verisys API credentials (API Key and optionally API Secret)
2. Register at NADRA Verisys Portal to get credentials
3. Complete KYC and API access approval process

🎯 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

Use sandbox mode for testing without affecting production data:

final client = VerisysClient(
  apiKey: 'sandbox-api-key',
  useSandbox: true,
);

Test CNICs

Use these test CNICs in sandbox mode:

• 1234567890123 - Valid CNIC (will verify successfully)
• 9876543210987 - Invalid CNIC (verification will fail)
• 1111111111111 - Not found (CNIC not in database)

📱 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: [e-mail]

🔗 Related Packages

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

⚖️ Disclaimer

This is an unofficial package and is not affiliated with NADRA. Use at your own risk and ensure compliance with NADRA's terms of service and Pakistani data protection laws.

🌟 Show Your Support

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

---

Made with ❤️ by Ishaque Hassan