iban4j

IBAN validation often requires more than just the standard ISO 7064 MOD 97-10 check. Many countries implement specific 'National Check Digit' algorithms to validate the internal structure of the account number (BBAN), bank codes, or branch codes.

When using iban4j, be aware that different countries use different mathematical models, such as:

• Modulus 11 with weights: Used in the Czech Republic, Slovak Republic, and Spain.
• Modulus 10 with weights: Used in Finland and Estonia (7-3-1 method).
• Modulus 97 variations: Used in Belgium, France, and Tunisia.
• Custom character transformations: Italy uses specific odd/even position transformations for alphanumeric characters.

If you are implementing custom validation logic or verifying why a specific IBAN might fail standard checks, refer to the country-specific documentation for the exact weight tables and transformation rules.

IBAN validation can be performed using IbanUtil or IbanValidator.

Standard Validation

By default, IbanUtil.validate(string) performs standard IBAN checks (format and check digits). If validation fails, it throws one of the following exceptions:

• IbanFormatException
• InvalidCheckDigitException
• UnsupportedCountryException

Country-Specific Rules (Opt-in)

To enable national check digit validation (e.g., specific rules for France), you must explicitly opt-in. This is disabled by default.

Ways to enable country rules:

1. Per-call: Use IbanUtil.isValid(string, config) where config is built via ValidationConfig.builder().enableNationalCheckDigitValidation(true).build().
2. Reusable Validator: Use IbanValidator.builder().enableCountryRules().build().
3. Convenience Helpers: Use IbanUtil.validateWithCountryRules(string) or IbanUtil.isValidWithCountryRules(string).

Note: When country rules fail, IbanValidator.validate(...) throws an IbanFormatException with the violation COUNTRY_RULES_FAILED.

try {
    // Standard validation
    IbanUtil.validate("AT611904300234573201");
} catch (IbanFormatException | InvalidCheckDigitException | UnsupportedCountryException ex) {
    System.err.println("IBAN is invalid: " + ex.getMessage());
}

// Opt-in to country rules via ValidationConfig
ValidationConfig config = ValidationConfig.builder()
    .enableNationalCheckDigitValidation(true)
    .build();
boolean valid = IbanUtil.isValid("FR1420041010050500013M02606", config);

// Using a reusable validator with country rules
IbanValidator validator = IbanValidator.builder()
    .enableCountryRules()
    .build();
validator.validate("FR1420041010050500013M02606");

You can create IBAN objects using a Builder for full control, or parse existing IBAN strings using Iban.valueOf().

Using the Builder

Use Iban.Builder to specify the countryCode, bankCode, and accountNumber. You can also enable leftPadding(true) to pad codes with zeros (or a custom paddingCharacter) and use buildRandom() to generate a random IBAN for a specific country.

Parsing Strings

• Raw IBANs: Use Iban.valueOf("STRING").
• Formatted IBANs: Use Iban.valueOf("STRING", IbanFormat.Default) to handle strings with spaces or specific formatting.

// Generate via Builder
Iban iban = new Iban.Builder()
    .countryCode(CountryCode.AT)
    .bankCode("19043")
    .accountNumber("00234573201")
    .build();

// Parse raw string
Iban iban = Iban.valueOf("DE89370400440532013000");

// Parse formatted string
Iban iban = Iban.valueOf("DE89 3704 0044 0532 0130 00", IbanFormat.Default);

// Generate random IBAN for a country
Iban randomIban = Iban.random(CountryCode.AT);

This reference provides the specific mathematical algorithms used for national check digit validation across various countries. Use these details if you need to implement custom validation or understand the underlying structure of a country's BBAN.

### Belgium
Dividing the first 10 digits by 97. If remainder is 00, check digits are 97. Otherwise, check digits are the remainders.

### Bosnia and Herzegovina
ISO 7064 MOD 97-10 over the entire account number.

### Croatia
ISO 7064-MOD 11, 10 for both bank code and account number. No check digit for the entire structure.

### Czech Republic
Modulus 11 with weights:
1. Prefix: 10, 5, 8, 4, 2, 1
2. Basic: 6, 3, 7, 9, 10, 5, 8, 4, 2, 1

### Estonia
7-3-1 method: weights 7,3,1,7,3... from right to left. Sum is subtracted from the next nearest multiple of ten.

### Finland
Modulus 10 with weights 2, 1, 2, 1 from right to left on the first 13 digits.

### France
Modulus 97 on RIB (5-5-11-2 digits). Includes letter-to-digit conversion:
| AJ | BKS | CLT | DMU | ENV | FOW | GPX | HQY | IRZ |
|----|-----|-----|-----|-----|-----|-----|-----|-----|
| 1  | 2   | 3   | 4   | 5   | 6   | 7   | 8   | 9   |

### Iceland
Modulus 11 on the first eight digits of kennitala. Weights 2, 3, 4, 5, 6, 7 (repeating) from right to left.

### Italy
Alphanumeric transformation based on odd/even positions, followed by division by 26 to find the alphabetic check digit (0=A, 1=B, etc.).

### Netherlands
Modulus 11 with weights 1 to 10 (right to left). Note: Postbank accounts (starting with 3 zeros) may not have strict validation.

### Norway
Modulus 11 with weights 5, 4, 3, 2, 7, 6, 5, 4, 3, 2 (left to right).

### Spain
Modulus 11 with weights 1, 2, 4, 8, 5, 10, 9, 7, 3, 6. If remainder is 10 or 11, check digit becomes 1 or 0 respectively.

### Tunisia
Similar to France: Modulus 97 on the 18-character RIB, then Modulus 97 on the 20-character full number.