Romanian eID & Passport NFC Reader SDK for React Native
npm install @up2date/romanian-eid-sdkRomanian eID & Passport NFC Reader SDK for React Native. Read Romanian electronic identity documents (ePassports and ID cards) using NFC technology.


Enhanced CSCA Validation & SDK Upgrade!
authenticationResult property with comprehensive CSCA validation detailsauthentic (all checks passed), failed (card suspect), warning (partial verification)Automatic NFC Lifecycle Management:
- ⨠Zero Configuration NFC - No more manual NFC setup code in MainActivity
- š Automatic Lifecycle Handling - SDK manages all NFC events automatically
- š Simplified Integration - Just add permissions & intent filters, that's it!
- š± Works Out of the Box - NFC detection and card reading work immediately
issueDate ā dateOfIssueexpiryDate ā dateOfExpiryaddress field for general address informationcscaValidated, cscaCountry, cscaValidationMessage- ā
NFC Passport Reading - Read Romanian ePassports using BAC/PACE protocols
- ā
NFC ID Card Reading - Read Romanian electronic ID cards using PACE
- ā
Automatic NFC Handling - Zero configuration NFC setup
- ā
Detailed CSCA Validation - Comprehensive Passive Authentication with status, reasons, and details (NEW in v1.4.7!)
- ā
MRZ Scanning - Camera-based MRZ (Machine Readable Zone) scanning
- ā
OCR Scanning - Extract data from old non-NFC ID cards using OCR
- ā
Biometric Extraction - Extract photos and signatures from documents
- ā
ICAO 9303 Compliant - Full compliance with international standards
- ā
License Management - Secure JWT-based license system
- ā
TypeScript Support - Full TypeScript definitions included
- ā
Android SDK v1.5.3 - Latest native SDK with improved reliability (NEW in v1.4.7!)
``bash`
npm install @up2date/romanian-eid-sdkor
yarn add @up2date/romanian-eid-sdk
1. Install CocoaPods dependencies:
`bash`
cd ios && pod install
> Note: The SDK uses React Native autolinking - no manual Podfile configuration needed! If you have an old manual pod reference like pod 'RNRomanianEIDSDK', :path => ..., please remove it.
2. Add required capabilities to your Info.plist:
`xml
`
3. Enable NFC capability in Xcode:
- Open your project in Xcode
- Select your target ā Signing & Capabilities
- Click "+ Capability" ā Near Field Communication Tag Reading
4. Add the RomanianEIDSDK.xcframework to your project (already included in the pod).
#### 1. Add NFC Permissions and Intent Filters
Add the following to your AndroidManifest.xml:
`xml
android:required="false" />
android:required="false" />
android:exported="true"
android:launchMode="singleTask">
android:resource="@xml/nfc_tech_filter" />
`
#### 2. Create NFC Tech Filter
Create file android/app/src/main/res/xml/nfc_tech_filter.xml:
`xml`
#### 3. Update MainActivity to Extend EIDReactActivity
Update your MainActivity.kt to extend EIDReactActivity instead of ReactActivity:
`kotlin
package com.yourapp
import com.facebook.react.ReactActivityDelegate
import com.facebook.react.defaults.DefaultNewArchitectureEntryPoint.fabricEnabled
import com.facebook.react.defaults.DefaultReactActivityDelegate
import com.rnromanianeidsdk.EIDReactActivity
class MainActivity : EIDReactActivity() {
override fun getMainComponentName(): String = "YourApp"
override fun createReactActivityDelegate(): ReactActivityDelegate =
DefaultReactActivityDelegate(this, mainComponentName, fabricEnabled)
}
`
That's it! š By extending EIDReactActivity, the SDK automatically handles all NFC lifecycle management:
- Registers for NFC events when the app starts
- Enables/disables NFC foreground dispatch as needed
- Detects and processes NFC cards automatically
- Handles all activity lifecycle callbacks
> Note: The key change from standard React Native is using EIDReactActivity instead of ReactActivity. This provides automatic NFC lifecycle management without any additional code.
`typescript
import EIDReader from '@up2date/romanian-eid-sdk';
// Initialize with your license key
await EIDReader.initialize('YOUR_LICENSE_KEY_JWT');
`
`typescript
// Scan MRZ first (optional, or enter manually)
const mrzResult = await EIDReader.startMRZScanning();
// Read passport via NFC
const result = await EIDReader.readPassport(mrzResult.mrzKey, {
enableCSCAValidation: true,
timeout: 60,
});
console.log('Name:', result.fullName);
console.log('Document:', result.documentNumber);
console.log('Photo:', result.facialImageBase64); // base64 encoded image
`
`typescript
// Read electronic ID card via NFC
const result = await EIDReader.readIDCard(
'123456', // CAN (6 digits)
'1234', // PIN (4-8 digits)
{
enableCSCAValidation: true,
readPhoto: true,
readSignature: true,
timeout: 90,
}
);
// Check authentication result (NEW in v1.4.7!)
if (result.authenticationResult) {
switch (result.authenticationResult.status) {
case 'authentic':
console.log('ā
Card is authentic!');
console.log(result.authenticationResult.message);
// Safe to use card data
break;
case 'failed':
console.error('ā Card authentication FAILED!');
console.error('Reason:', result.authenticationResult.reason);
console.error('Details:', result.authenticationResult.details);
// DO NOT accept this card as valid
return;
case 'warning':
console.warn('ā ļø Partial authentication');
console.warn(result.authenticationResult.message);
// Decide based on your security policy
break;
}
}
console.log('CNP:', result.cnp);
console.log('Name:', result.fullName);
console.log('Date of Issue:', result.dateOfIssue);
console.log('Date of Expiry:', result.dateOfExpiry);
console.log('Address:', result.address);
console.log('Photo:', result.facialImageBase64 ? 'Available' : 'N/A');
`
`typescript
// For old non-NFC ID cards
const result = await EIDReader.startOCRScanning();
if (result.isReliable) {
console.log('CNP:', result.cnp);
console.log('Name:', result.fullName);
console.log('Confidence:', result.confidence);
} else {
console.warn('Low confidence:', result.validationIssues);
}
`
#### initialize(license: string): Promise
Initialize SDK with license key.
`typescript`
await EIDReader.initialize('eyJhbGciOiJIUzI1NiIs...');
#### readPassport(mrzKey: string, options?: PassportReadOptions): Promise
Read Romanian ePassport via NFC.
Parameters:
- mrzKey - MRZ key (format: DocumentNumber+DOB+Expiry with check digits)options
- - Optional configuration
Options:
`typescript`
{
enableCSCAValidation?: boolean; // Default: true
timeout?: number; // Default: 60 seconds
}
Returns: PassportResult with document data and biometrics.
#### readIDCard(can: string, pin: string, options?: IDCardReadOptions): Promise
Read Romanian electronic ID card via NFC.
Parameters:
- can - Card Access Number (6 digits printed on card)pin
- - Personal PIN (4-8 digits)options
- - Optional configuration
Options:
`typescript`
{
enableCSCAValidation?: boolean; // Default: true
readPhoto?: boolean; // Default: true
readSignature?: boolean; // Default: true
timeout?: number; // Default: 90 seconds
}
Returns: IDCardResult with personal data, addresses, and biometrics.
#### startMRZScanning(): Promise
Open camera to scan MRZ from passport.
Returns: MRZScanResult with parsed MRZ data and mrzKey for NFC reading.
#### startOCRScanning(): Promise
Open camera to scan old non-NFC ID card using OCR.
Returns: OCRScanResult with extracted data and confidence scores.
#### isNFCAvailable(): Promise
Check if NFC is available and SDK is initialized.
#### getLicenseInfo(): Promise
Get current license information.
`typescript${event.percentage}%: ${event.message}
// Progress updates during NFC reading
const subscription = EIDReader.onReadProgress((event) => {
console.log();
});
// Remember to unsubscribe
subscription.remove();
// or
EIDReader.removeAllListeners();
`
#### PassportResult
`typescript`
{
success: boolean;
documentNumber: string;
fullName: string;
dateOfBirth: string;
nationality: string;
sex: string;
dateOfExpiry: string;
cnp?: string;
placeOfBirth?: string;
residenceAddress?: string;
phoneNumber?: string;
facialImageBase64?: string; // JPEG base64
signatureImageBase64?: string; // PNG base64
cscaValidated: boolean;
cscaCountry?: string;
errorMessage?: string;
}
#### IDCardResult
`typescript
{
success: boolean;
documentNumber: string;
cnp: string;
fullName: string;
dateOfBirth: string;
sex: string;
dateOfExpiry: string; // Updated property name (v1.4.7)
dateOfIssue?: string; // Updated property name (v1.4.7)
issuingAuthority?: string;
placeOfBirth?: string;
citizenship?: string;
address?: string; // NEW in v1.4.7
permanentAddress?: string;
temporaryAddress?: string;
foreignAddress?: string;
facialImageBase64?: string;
signatureImageBase64?: string;
// NEW in v1.4.7: Detailed authentication result
authenticationResult?: {
status: 'authentic' | 'failed' | 'warning';
message: string;
reason?: string; // Only present when status is "failed"
details?: string;
};
// Deprecated fields (for backward compatibility)
cscaValidated: boolean; // Use authenticationResult.status instead
cscaCountry?: string; // Use authenticationResult.details instead
cscaValidationMessage?: string; // Use authenticationResult.message instead
errorMessage?: string;
}
`
`typescript`
try {
const result = await EIDReader.readPassport(mrzKey);
} catch (error) {
switch (error.code) {
case 'NFC_NOT_AVAILABLE':
console.error('NFC not available on this device');
break;
case 'INVALID_MRZ':
console.error('Invalid MRZ key');
break;
case 'USER_CANCELLED':
console.log('User cancelled the operation');
break;
case 'READ_TIMEOUT':
console.error('Reading timed out');
break;
case 'LICENSE_INVALID':
console.error('Invalid or expired license');
break;
default:
console.error('Error:', error.message);
}
}
Starting with v1.4.7, the SDK provides detailed authentication results through the authenticationResult property. This indicates whether the electronic ID card is authentic and if the data has not been tampered with.
Passive Authentication (PA) is a security mechanism that verifies:
1. SOD Signature - The Security Object Document (SOD) is signed by the Document Signer (DS) certificate
2. Data Integrity - Hashes of all data groups (DG1, DG2, etc.) match the hashes stored in the SOD
3. Certificate Chain - The DS certificate is signed by a trusted Country Signing Certificate Authority (CSCA)
The authenticationResult.status field can have three values:
#### authentic - Card is Genuine ā
All security checks passed. The card is authentic and data has not been modified.
`typescript`
if (result.authenticationResult?.status === 'authentic') {
// Safe to trust all data from the card
console.log('Card verified:', result.authenticationResult.message);
// Proceed with user registration/authentication
}
#### failed - Card is Suspect or Fake ā
Critical security checks failed. The card may be counterfeit or data has been tampered with.
`typescript
if (result.authenticationResult?.status === 'failed') {
console.error('SECURITY ALERT!');
console.error('Reason:', result.authenticationResult.reason);
console.error('Details:', result.authenticationResult.details);
// DO NOT accept this card
// Log the incident for security review
// Alert security personnel
}
`
Common failure reasons:
- Invalid SOD signature
- Data hash mismatch (tampered data)
- Invalid certificate chain
- Expired or revoked certificates
#### warning - Partial Verification ā ļø
Some checks passed, but complete verification couldn't be performed. Decide based on your security policy.
`typescript
if (result.authenticationResult?.status === 'warning') {
console.warn('Partial verification:', result.authenticationResult.message);
// Example: CSCA certificate not available in local database
// Decision depends on your security requirements:
// - High security: Reject and request alternative ID
// - Medium security: Accept with additional verification steps
// - Low security: Accept with logged warning
}
`
Common warning reasons:
- CSCA certificate not available in local database
- Offline mode with incomplete certificate store
- New CSCA certificates not yet synchronized
1. Always Enable CSCA Validation
`typescript`
const result = await EIDReader.readIDCard(can, pin, {
enableCSCAValidation: true // Recommended!
});
2. Handle All Three Status Cases
`typescript`
switch (result.authenticationResult?.status) {
case 'authentic':
// Proceed normally
break;
case 'failed':
// Reject and alert security
break;
case 'warning':
// Apply your security policy
break;
}
3. Log Authentication Results
- Log all failed authentications for security review
- Monitor warning patterns to identify missing certificates
- Keep audit trail for compliance
4. Backward Compatibility
- The legacy cscaValidated boolean field is still availableauthenticationResult
- For new code, always use for more detail
Old code (still works):
`typescript`
if (result.cscaValidated) {
console.log('Valid:', result.cscaValidationMessage);
}
New code (recommended):
`typescript`
if (result.authenticationResult?.status === 'authentic') {
console.log('Valid:', result.authenticationResult.message);
} else if (result.authenticationResult?.status === 'failed') {
console.error('Failed:', result.authenticationResult.reason);
}
A complete example app is included in the example/ directory. To run it:
`bashInstall dependencies
cd example
yarn install
The example app demonstrates:
- Passport reading with MRZ scanning
- ID card reading with CAN/PIN input
- OCR scanning for old cards
- License status display
- Authentication result handling (v1.4.7+)
This SDK is commercial software. A valid license key is required for use.
For licensing information, contact: office@up2date.ro
- Email: office@up2date.ro
- Documentation: Full API Docs
- Issues: GitHub Issues
- All NFC communication is encrypted (BAC/PACE protocols)
- No data is sent to external servers
- CSCA validation performed locally
- Biometric data never leaves the device
- License validation done via JWT
Developed by Up2Date Software
Ā© 2025 Up2Date. All rights reserved.