https://github.com/arturmkrtchyan/iban4j
A Java library for generation and validation of the International Bank Account Numbers (IBAN ISO_13616) and Business Identifier Codes (BIC ISO_9362).
https://github.com/arturmkrtchyan/iban4j
Last synced: 8 days ago
JSON representation
A Java library for generation and validation of the International Bank Account Numbers (IBAN ISO_13616) and Business Identifier Codes (BIC ISO_9362).
- Host: GitHub
- URL: https://github.com/arturmkrtchyan/iban4j
- Owner: arturmkrtchyan
- License: apache-2.0
- Created: 2013-09-03T19:59:23.000Z (over 12 years ago)
- Default Branch: master
- Last Pushed: 2026-03-08T12:24:26.000Z (about 1 month ago)
- Last Synced: 2026-03-08T13:53:11.353Z (about 1 month ago)
- Language: Java
- Homepage: http://iban4j.org
- Size: 1.59 MB
- Stars: 297
- Watchers: 19
- Forks: 133
- Open Issues: 38
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- awesome - arturmkrtchyan/iban4j - A Java library for generation and validation of the International Bank Account Numbers (IBAN ISO_13616) and Business Identifier Codes (BIC ISO_9362). (<a name="Java"></a>Java)
README
iban4j
======
A Java library for the generation, validation, and parsing of
International Bank Account Numbers (IBAN) and Business Identifier Codes (BIC).
[](https://github.com/arturmkrtchyan/iban4j/actions/workflows/java-ci.yml) [](https://coveralls.io/r/arturmkrtchyan/iban4j) [](https://central.sonatype.com/artifact/org.iban4j/iban4j)
[](https://raw.githubusercontent.com/arturmkrtchyan/iban4j/master/LICENSE.txt)
---
### Features
- **IBAN Generation and Validation**:
Supports creating valid IBANs and verifying their format and check digits.
- **BIC Validation**:
Checks the validity of Business Identifier Codes.
- **Multiple Formats**:
Handles both standard and formatted string representations.
- **Customizable Padding**:
Offers options for zero-padding account and bank codes.
---
## Getting Started
### Maven Dependency
To use **iban4j** in your Maven project, add the following dependency to your `pom.xml`:
```xml
org.iban4j
iban4j
3.2.13-RELEASE
````
#### Gradle Dependency
To include **iban4j** into your Gradle project, add the following dependency to your `build.gradle` or `build.gradle.kts` file.
For a **Groovy DSL** (`build.gradle`) file:
```groovy
dependencies {
implementation 'org.iban4j:iban4j:3.2.13-RELEASE'
}
```
For a **Kotlin DSL** (`build.gradle.kts`) file:
```kotlin
dependencies {
implementation("org.iban4j:iban4j:3.2.13-RELEASE")
}
```
After adding the dependency, run `gradle build`. Gradle will automatically download the library and include it in your project.
-----
### Usage Examples
#### IBAN Examples
##### Generate an IBAN
```java
// Using the Builder pattern
Iban iban = new Iban.Builder()
.countryCode(CountryCode.AT)
.bankCode("19043")
.accountNumber("00234573201")
.build();
```
##### Create an `Iban` object from a string
```java
// From a raw IBAN string
Iban iban = Iban.valueOf("DE89370400440532013000");
// From a formatted IBAN string
Iban iban = Iban.valueOf("DE89 3704 0044 0532 0130 00", IbanFormat.Default);
```
##### Generate a random IBAN
```java
// For a specific country
Iban iban = Iban.random(CountryCode.AT);
// For a random country
Iban iban = Iban.random();
// Using the builder for more control
Iban iban = new Iban.Builder()
.countryCode(CountryCode.AT)
.bankCode("19043")
.buildRandom();
```
##### Validate an IBAN
```java
try {
// Validate a raw IBAN
IbanUtil.validate("AT611904300234573201");
// Validate a formatted IBAN
IbanUtil.validate("DE89 3704 0044 0532 0130 00", IbanFormat.Default);
System.out.println("IBAN is valid");
} catch (IbanFormatException | InvalidCheckDigitException | UnsupportedCountryException ex) {
System.err.println("IBAN is invalid: " + ex.getMessage());
}
```
##### Validate with country-specific rules (opt-in)
By default, only the standard IBAN checks are performed. You can optionally enable country-specific rules (e.g., national check digit) per call or via a reusable validator:
```java
// Per-call opt-in using a config
ValidationConfig config = ValidationConfig.builder()
.enableNationalCheckDigitValidation(true) // enable country rules
.build();
boolean valid = IbanUtil.isValid("FR1420041010050500013M02606", config);
// Or throw on failure via the instance-based validator
IbanValidator validator = IbanValidator.builder()
.enableCountryRules() // equivalent to enabling national check digit rules
.build();
validator.validate("FR1420041010050500013M02606");
```
Convenience helpers are also available when you always want country rules enabled:
```java
IbanUtil.validateWithCountryRules("FR1420041010050500013M02606");
boolean valid = IbanUtil.isValidWithCountryRules("FR1420041010050500013M02606");
```
Notes:
- Country-specific rules are opt-in and disabled by default to preserve existing behavior.
- When enabled and a country rule fails, `IbanFormatException` with violation `COUNTRY_RULES_FAILED` is thrown by `IbanValidator.validate(...)`.
##### Enable left-padding for generated IBANs
```java
// Left-pad account number, bank code, and branch code with zeros
Iban iban = new Iban.Builder()
.leftPadding(true)
.countryCode(CountryCode.DE)
.bankCode("66280099")
.accountNumber("123456700")
.build();
// Change the default padding character from '0' to '1'
Iban ibanWithCustomPadding = new Iban.Builder()
.leftPadding(true)
.paddingCharacter('1')
.countryCode(CountryCode.DE)
.bankCode("66280099")
.accountNumber("123456700")
.build();
```
#### BIC Examples
##### Create a `Bic` object from a string
```java
Bic bic = Bic.valueOf("DEUTDEFF");
```
##### Validate a BIC
```java
try {
BicUtil.validate("DEUTDEFF500");
System.out.println("BIC is valid");
} catch (BicFormatException ex) {
System.err.println("BIC is invalid: " + ex.getMessage());
}
```
-----
### Compatibility
This library requires [Java 11](https://adoptium.net/temurin/releases/?version=11) or higher.
-----
### References
- [ISO 13616 International Bank Account Number (IBAN)](http://en.wikipedia.org/wiki/ISO_13616)
- [ISO 9362 Business Identifier Codes (BIC)](http://en.wikipedia.org/wiki/ISO_9362)
- [ECB IBAN Registry](https://www.ecb.europa.eu/paym/retpaym/paymint/sepa/shared/pdf/iban_registry.pdf)
-----
### License
Copyright 2015 Artur Mkrtchyan.
Licensed under the Apache License, Version 2.0: [http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0)