Core interfaces and algorithms for the Finova financial toolkit.
Contains Mod97, Luhn, ISO 7064, and base models for IBAN/BIC/Card/Enterprise/NationalID
validation.
Zero dependencies.
69 countries: All 27 EU + UK, CH, NO, Middle East (AE, BH, IL, OM, SA), Asia (CN, JP, KR, KZ, VN, PK, ID), Americas (AR, BR, CA, CL, CO, MX, US), Africa (ZA, KE), Oceania (NZ) and more
Enterprise Number
Business registration
🇧🇪 Belgium (BCE/KBO), 🇱🇺 Luxembourg (RCS), 🇳🇱 Netherlands (KvK), 🇮🇪 Ireland (CRO), 🇲🇹 Malta (Company No.), 🇸🇰 Slovakia (IČO), 🇸🇮 Slovenia (Matična), 🇸🇪 Sweden (Org.nr), 🇿🇦 South Africa (CIPC), 🇳🇿 New Zealand (NZBN)
EIN
Employer Identification Number
🇺🇸 USA
LEI
Legal Entity Identifier
🌍 ISO 17442 worldwide
🆔 National Identity
Region
Countries
ID Types
Western Europe
BE, FR, DE, NL, UK, AT, CH
Belgian NN, French NIR, German Steuer-ID, Dutch BSN, UK NINO
using Finova.Core.Iban;
using Finova.Core.PaymentCard;
using Finova.Core.Identifiers;
using Finova.Services;
// Global IBAN Validation (supports all IBAN-enabled countries worldwide)
var result = GlobalIbanValidator.ValidateIban("BR1800360305000010009795493C1");
if (result.IsValid)
{
Console.WriteLine("Valid Brazilian IBAN!");
}
// Country-specific IBAN Validation
var ibanService = new IbanService();
var result = ibanService.Validate("BE68 5390 0754 7034");
if (result.IsValid)
{
var details = ibanService.Parse("BE68 5390 0754 7034");
Console.WriteLine($"Country: {details.CountryCode}");
Console.WriteLine($"BBAN: {details.Bban}");
Console.WriteLine($"Check Digits: {details.CheckDigits}");
}
// BBAN Validation (Basic Bank Account Number)
var bbanService = serviceProvider.GetRequiredService<IBbanService>();
var bbanResult = bbanService.Validate("BE", "539007547034");
if (bbanResult.IsValid)
{
var bbanDetails = bbanService.Parse("BE", "539007547034");
Console.WriteLine($"Country: {bbanDetails.CountryCode}"); // BE
Console.WriteLine($"BBAN: {bbanDetails.Bban}"); // 539007547034
}
// Payment Card Validation
var cardValidator = new PaymentCardValidator();
var cardResult = cardValidator.Validate("4111111111111111");
if (cardResult.IsValid)
{
var cardDetails = cardValidator.Parse("4111111111111111");
Console.WriteLine($"Brand: {cardDetails.Brand}"); // Visa
}
// ISIN Validation (Securities)
var isinValidator = new IsinValidator();
var isinResult = isinValidator.Validate("US0378331005");
if (isinResult.IsValid)
{
var isinDetails = isinValidator.Parse("US0378331005");
Console.WriteLine($"Country: {isinDetails.CountryCode}"); // US
Console.WriteLine($"NSIN: {isinDetails.Nsin}"); // 037833100
}
Dependency Injection
using Finova.Extensions;
// Register all Finova services
services.AddFinova();
// Or register specific services
services.AddFinovaCore();
services.AddFinovaCountry<BelgiumModule>();
public class PaymentService
{
private readonly IIbanService _ibanService;
private readonly IVatValidator _vatValidator;
public PaymentService(IIbanService ibanService, IVatValidator vatValidator)
{
_ibanService = ibanService;
_vatValidator = vatValidator;
}
public bool ValidatePaymentDetails(string iban, string vatNumber)
{
return _ibanService.Validate(iban).IsValid
&& _vatValidator.Validate(vatNumber).IsValid;
}
}
FluentValidation Integration
using Finova.Extensions.FluentValidation;
public class PaymentRequestValidator : AbstractValidator<PaymentRequest>
{
public PaymentRequestValidator()
{
// 🏦 Banking
RuleFor(x => x.Iban).MustBeValidIban();
RuleFor(x => x.Bic).MustBeValidBic();
// 🇺🇸🇨🇦🇦🇺🇸🇬🇯🇵 Routing Numbers (Aliases)
RuleFor(x => x.UsRoutingNumber).MustBeValidABARoutingNumber(); // US ABA
RuleFor(x => x.CaTransitNumber).MustBeValidCanadianTransitNumber(); // Canada
RuleFor(x => x.AuBsb).MustBeValidAustralianBsb(); // Australia BSB
RuleFor(x => x.SgBankCode).MustBeValidSingaporeBankCode(); // Singapore
RuleFor(x => x.JpZengin).MustBeValidJapanZenginCode(); // Japan
// 💳 Payment Cards
RuleFor(x => x.CardNumber).MustBeValidPaymentCard();
RuleFor(x => x.VisaNumber).MustBeValidPaymentCardForBrand(PaymentCardBrand.Visa);
// 🏢 Enterprise & Tax IDs (Aliases)
RuleFor(x => x.Siret).MustBeValidSiret(); // France SIRET
RuleFor(x => x.Siren).MustBeValidSiren(); // France SIREN
RuleFor(x => x.Kbo).MustBeValidKbo(); // Belgium KBO/BCE
RuleFor(x => x.VatNumber).MustBeValidVat(); // EU VAT
// 📝 Payment References
RuleFor(x => x.Communication).MustBeValidIsoRf(); // ISO 11649 RF
RuleFor(x => x.Ogm).MustBeValidOgm(); // Belgian OGM
RuleFor(x => x.QrRef).MustBeValidSwissQrReference(); // Swiss QR
}
}
Country-Specific Validation
using Finova.Countries.Belgium;
using Finova.Countries.UnitedStates;
// Belgian validations
var belgiumIban = new BelgiumIbanValidator();
belgiumIban.Validate("BE68 5390 0754 7034"); // ✓
var belgiumVat = new BelgiumVatValidator();
belgiumVat.Validate("BE0123456789"); // ✓
var belgiumNationalId = new BelgiumNationalIdValidator();
belgiumNationalId.Validate("85.07.30-033.28"); // ✓
// US validations
var usRouting = new UnitedStatesRoutingNumberValidator();
usRouting.Validate("021000021"); // ✓
var usEin = new UnitedStatesEinValidator();
usEin.Validate("12-3456789"); // ✓
📋 Validation Rules Reference
IBAN Structure
Component
Length
Description
Country Code
2
ISO 3166-1 alpha-2
Check Digits
2
Mod 97 validation
BBAN
Variable
Country-specific format
Payment Card Validation
Brand
Prefix
Length
Algorithm
Visa
4
16
Luhn
Mastercard
51-55, 2221-2720
16
Luhn
American Express
34, 37
15
Luhn
Discover
6011, 644-649, 65
16
Luhn
Diners Club
36, 38, 300-305
14-16
Luhn
ISIN Structure
Component
Position
Description
Country Code
1-2
ISO 3166-1 alpha-2
NSIN
3-11
National Security ID
Check Digit
12
Luhn mod 10
📊 Test Coverage
Total Tests: 10,700+
Passing: 100%
Countries Covered: 110+
Validators: 100+
🗺️ Roadmap
Version
Status
Features
v1.0.0
✅ Released
Core IBAN, BIC, Payment Cards
v1.1.0
✅ Released
Payment References (BE, FI, NO, SE, CH)
v1.2.0
✅ Released
VAT validation, Enterprise Numbers
v1.3.0
✅ Released
National ID (51 European countries)
v1.4.0
🚀 Current
Global Expansion, Securities (ISIN, CUSIP, SEDOL), Currency
v1.5.0
📋 Planned
EPC QR Code generation, SEPA XML
v1.6.0
📋 Planned
Async validation, Batch processing
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
