Developer Interface

IBAN

class schwifty.IBAN(value: str, **kwargs: Any)

The IBAN object.

Examples

You create a new IBAN object by supplying an IBAN code in text form. The IBAN is validated behind the scenes and you can then access all relevant components as properties:

>>> iban = IBAN('DE89 3704 0044 0532 0130 00')
>>> iban.account_code
'0532013000'
>>> iban.bank_code
'37040044'
>>> iban.country_code
'DE'
>>> iban.checksum_digits
'89'
>>> iban.bban
<BBAN=370400440532013000>

Parameters:

• iban (str) – The IBAN code.

• allow_invalid (bool) – If set to True IBAN validation is skipped on instantiation.

• validate_bban (bool) – If set to True also check the country specific checksum of the BBAN.

Raises:

• InvalidStructure – If the IBAN contains invalid characters or the BBAN does not match the country specific format.

• InvalidChecksumDigits – If the IBAN’s checksum is invalid.

• InvalidBBANChecksum – If the country specific BBAN checksum is invalid and validate_bban was set to True.

• InvalidLength – If the length does not match the country specific specification.

Changed in version 2021.05.1: Added the validate_bban parameter that controls if the country specific checksum within the BBAN is also validated.

Changed in version 2023.10.0: The IBAN is now a subclass of str and supports all its methods.

Changed in version 2024.01.1: Added the bban-attribute that provideds all country specific account and bank information.

bban: BBAN

The Basic Bank Account Number (BBAN) holds all information about national bank and account identifiers in a format that is decided by the national central bank or a designated payment authority of each country. For ease of use most of the properties of the bban are proxied by the IBAN-class (e.g. account_code, bank_code).

classmethod from_bban(country_code: str, bban: str | BBAN, allow_invalid: bool = False, validate_bban: bool = False) → IBAN

Create an IBAN from a given BBAN.

This will automatically calculate the IBAN checksum digits.

Parameters:

• country_code (str) – The ISO 3166 alpha-2 country code.

• bban (str or BBAN) – The national Basic Bank Account Number.

• allow_invalid (bool) – If set to True IBAN validation is skipped on instantiation.

• validate_bban (bool) – If set to True also check the country specific checksum.

Added in version 2024.01.2.

classmethod generate(country_code: str, bank_code: str, account_code: str, branch_code: str = '', **kwargs: Any) → IBAN

Generate an IBAN from it’s components.

If the bank-code and/or account-number have less digits than required by their country specific representation, the respective component is padded with zeros.

Examples

To generate an IBAN do the following:

>>> bank_code = '37040044'
>>> account_code = '532013000'
>>> iban = IBAN.generate('DE', bank_code, account_code)
>>> iban.formatted
'DE89 3704 0044 0532 0130 00'

Parameters:

• country_code (str) – The ISO 3166 alpha-2 country code.

• bank_code (str) – The country specific bank-code.

• account_code (str) – The customer specific account-code.

Raises:

InvalidAccountCode – If the account code does not meet the national requirements.

Changed in version 2020.08.3: Added the branch_code parameter to allow the branch code (or sort code) to be specified independently.

Changed in version 2021.05.2: Added support for generating the country specific checksum of the BBAN for Belgian banks.

classmethod random(country_code: str = '', random: Random | None = None, use_registry: bool = True, **values: str) → IBAN

Generate a random IBAN.

With no further arguments a random bank from the registry will be selected as basis for the bank code and the BBAN structure. All other components, e.g. the account code will be generated with the alphabet allowed by the BBAN spec.

If a country_code is provided the possible values will be limited to banks of the respective country. Additional components of the IBAN (e.g. the bank code) can be provided as keyword arguments to further narrow down the genreated values.

If use_regsitry is set to False the bank information from schwifty’s registry will be ignored and a completely random bank code will be generated.

Parameters:

• country_code (str) – The ISO 3166 alpha-2 country code.

• random (Random) – An alternative random number generator.

• use_registry (bool) – Select a random bank from the existing bank registry if available.

• values – The country specific BBAN components that should be taken as is and not be generated.

Raises:

GenerateRandomOverflowError – If no valid random value can be gerated after multiple tries.

validate(validate_bban: bool = False) → bool

Validate the structural integrity of this IBAN.

This function will verify the country specific format as well as the Luhn checksum in the 3rd and 4th position of the IBAN. For some countries (currently Belgium, Germany and Italy) it will also verify the correctness of the country specific checksum within the BBAN if the validate_bban parameter is set to True. For German banks it will pick the appropriate algorithm based on the bank code and verify that the account code has the correct checksum.

Note

You have to use the allow_invalid paramter when constructing the IBAN-object to circumvent the implicit validation.

Raises:

• InvalidStructure – If the IBAN contains invalid characters or the BBAN does not match the country specific format.

• InvalidChecksumDigits – If the IBAN’s checksum is invalid.

• InvalidBBANChecksum – If the country specific BBAN checksum is invalid.

• InvalidLength – If the length does not match the country specific specification.

Changed in version 2021.05.1: Added the validate_bban parameter that controls if the country specific checksum within the BBAN is also validated.

property account_code: str

The domestic account-code

Type:

str

property account_holder_id: str

Account holder’s national identification.

This value is only available for Iceland.

Type:

str

property account_id: str

Holder specific account identification.

This is currently only available for Brazil.

Type:

str

property account_type: str

Account type specifier.

This value is only available for Seychelles, Brazil and Bulgaria.

Type:

str

property bank: dict | None

The information of the bank related to the bank code as part of the BBAN

Type:

dict or None

property bank_code: str

The country specific bank-code.

Type:

str

property bank_name: str | None

The name of the bank associated with the IBAN bank code.

Examples

>>> IBAN('DE89370400440532013000').bank_name
'Commerzbank'

Added in version 2022.04.2.

Type:

str or None

property bank_short_name: str | None

The name of the bank associated with the IBAN bank code.

Examples

>>> IBAN('DE89370400440532013000').bank_short_name
'Commerzbank Köln'

Added in version 2022.04.2.

Type:

str or None

property bic: BIC | None

The BIC associated to the IBAN’s bank-code.

If the bank code is not available in schwifty’s registry None is returned.

Changed in version 2020.08.1: Returns None if no appropriate BIC can be constructed.

Type:

BIC or None

property branch_code: str

The branch-code of the bank if available.

Type:

str

property checksum_digits: str

Two digit checksum of the BBAN.

Type:

str

property country: Data | None

The country this IBAN is registered in.

Type:

Country

property country_code: str

ISO 3166 alpha-2 country code.

Type:

str

property formatted: str

The IBAN formatted in blocks of 4 digits.

Type:

str

property in_sepa_zone: bool

Is the country in the Single Euro Payments Area (SEPA) zone.

Added in version 2024.01.1.

Type:

bool

property is_valid: bool

Indicate if this is a valid IBAN.

Note

You have to use the allow_invalid paramter when constructing the IBAN-object to circumvent the implicit validation.

Examples

>>> IBAN('AB1234567890', allow_invalid=True).is_valid
False

Added in version 2020.08.1.

Type:

bool

property national_checksum_digits: str

National checksum digits.

Added in version 2024.01.1.

Type:

str

property numeric: int

A numeric represenation of the IBAN.

Type:

int

property spec: dict[str, Any]

The country specific IBAN specification.

Type:

dict

BBAN

class schwifty.BBAN(country_code: str, value: str, **kwargs: Any)

The Basic Bank Account Number (BBAN).

The format is decided by the national central bank or designated payment authority of each country.

Examples

Most commonly BBAN-objects are created implicitly by the IBAN-class, but they can also be instantiated like so:

>>> BBAN.from_components("DE", account_code="0532013000", bank_code="37040044")
<BBAN=370400440532013000>

Parameters:

• country_code (str) – A two-letter ISO 3166-1 compliant country code

• value (str) – The country specific BBAN value.

Added in version 2024.01.1.

classmethod from_components(country_code: str, **values: str) → BBAN

Generate a BBAN from its national components.

The currently supported values are bank_code, branch_code and account_code.

Parameters:

• country_code (str) – The ISO 3166 alpha-2 country code.

• values – The country specific BBAN components.

Raises:

InvalidAccountCode – If the account code does not meet the national requirements.

classmethod random(country_code: str = '', random: Random | None = None, use_registry: bool = True, **values: str) → BBAN

Generate a random BBAN.

With no further arguments a random bank from the registry will be selected as basis for the bank code and the BBAN structure. All other components, e.g. the account code will be generated with the alphabet allowed by the BBAN spec.

If a country_code is provided the possible values will be limited to banks of the respective country. Additional components of the IBAN (e.g. the bank code) can be provided as keyword arguments to further narrow down the genreated values.

If use_regsitry is set to False the bank information from schwifty’s registry will be ignored and a completely random bank code will be generated.

Parameters:

• country_code (str) – The ISO 3166 alpha-2 country code.

• random (Random) – An alternative random number generator.

• use_registry (bool) – Select a random bank from the existing bank registry if available.

• values – The country specific BBAN components that should be taken as is and not be generated.

Raises:

GenerateRandomOverflowError – If no valid random value can be gerated after multiple tries.

validate_national_checksum() → bool

bool: Validate the national checksum digits.

Raises:

InvalidBBANChecksum – If the country specific BBAN checksum is invalid.

property account_code: str

The domestic account-code

Type:

str

property account_holder_id: str

Account holder’s national identification.

This value is only available for Iceland.

Type:

str

property account_id: str

Holder specific account identification.

This is currently only available for Brazil.

Type:

str

property account_type: str

Account type specifier.

This value is only available for Seychelles, Brazil and Bulgaria.

Type:

str

property bank: dict | None

The information of bank related to this BBANs bank code.

Type:

dict | None

property bank_code: str

The country specific bank-code.

Type:

str

property bank_name: str | None

The name of the bank associated with the IBAN bank code.

Examples

>>> IBAN('DE89370400440532013000').bank_name
'Commerzbank'

Type:

str or None

property bank_short_name: str | None

The name of the bank associated with the IBAN bank code.

Examples

>>> IBAN('DE89370400440532013000').bank_short_name
'Commerzbank Köln'

Type:

str or None

property bic: BIC | None

The BIC associated to the BBAN’s bank-code.

If the bank code is not available in schwifty’s registry None is returned.

Type:

BIC or None

property branch_code: str

The branch-code of the bank if available.

Type:

str

property national_checksum_digits: str

National checksum digits if available.

Type:

str

property spec: dict[str, Any]

The country specific BBAN specification.

Type:

dict

BIC

class schwifty.BIC(value: str, **kwargs: Any)

The BIC object.

When creating an instance of a BIC the provided value is checked for correctnes, unless the allow_invalid parameter is set to True.

The validation is done in the context of ISO 9362:2022, which allows numbers in the business party prefix (the first 4 chracters). If strict SWIFT compliance is required the enforce_swift_compliance parameter can be set to True, in which case numbers are disallowed as described in revision 2023 of the SWIFT BIC policy.

Examples

You can either create a new BIC object by providing a code as text:

>>> bic = BIC('GENODEM1GLS')
>>> bic.country_code
'DE'
>>> bic.location_code
'M1'
>>> bic.bank_code
'GENO'

or by using the from_bank_code() classmethod:

>>> bic = BIC.from_bank_code('DE', '43060967')
>>> bic.formatted
'GENO DE M1 GLS'

Parameters:

• bic (str) – The BIC value.

• allow_invalid (bool) – If set to True validation is skipped on instantiation.

• enforce_swift_commpliance (bool) – If set to True the stricter SWIFT BIC policy is applied.

Raises:

• InvalidLength – If the BIC’s length is not 8 or 11 characters long.

• InvalidStructure – If the BIC contains unexpected characters.

• InvalidCountryCode – If the BIC’s country code is unknown.

Changed in version 2023.10.0: The BIC is now a subclass of str and supports all its methods.

Changed in version 2023.11.0: The validation of the BIC structure is now allowing numbers in the business party prefix, conforming to ISO 9362:2022. If strict SWIFT compliance should be ensured, the enforce_swift_compliance parameter can be set to True, which will then fall back to the previous validation method.

classmethod candidates_from_bank_code(country_code: str, bank_code: str) → list[BIC]

Create a list of potential BIC objects from country-code and domestic bank-code.

Examples

>>> bic_codes = BIC.candidates_from_bank_code("FR", "30004")
>>> bic_codes 
[<BIC=BNPAFRPPIFN>, <BIC=BNPAFRPPPAA>, <BIC=BNPAFRPPMED>,              <BIC=BNPAFRPPCRN>, <BIC=BNPAFRPP>, <BIC=BNPAFRPPPAE>, <BIC=BNPAFRPPPBQ>,
 <BIC=BNPAFRPPNFE>, <BIC=BNPAFRPPPGN>, <BIC=BNPAFRPPXXX>, <BIC=BNPAFRPPBOR>,
 <BIC=BNPAFRPPCRM>, <BIC=BNPAFRPPPVD>, <BIC=BNPAFRPPPTX>, <BIC=BNPAFRPPPAC>,
 <BIC=BNPAFRPPPLZ>, <BIC=BNPAFRPP039>, <BIC=BNPAFRPPENG>, <BIC=BNPAFRPPNEU>,
 <BIC=BNPAFRPPORE>, <BIC=BNPAFRPPPEE>, <BIC=BNPAFRPPPXV>, <BIC=BNPAFRPPIFO>]

>>> BIC.candidates_from_bank_code("DE", "20070024")
[<BIC=DEUTDEDBHAM>]

>>> BIC.candidates_from_bank_code("DE", "01010101")
Traceback (most recent call last):
...
InvalidBankCode: Unknown bank code '01010101' for country 'DE'

Parameters:

• country_code (str) – ISO 3166 alpha2 country-code.

• bank_code (str) – Country specific bank-code.

Returns:

a list of BIC objects generated from the given country code and bank code.

Return type:

list[BIC]

Raises:

InvalidBankCode – If the given bank code wasn’t found in the registry

Note

This currently only works for selected countries. Amongst them

• Andorra

• Austria

• Belgium

• Bosnia and Herzegovina

• Bulgaria

• Costa Rica

• Croatia

• Czech Republic

• Cyprus

• Denmark

• Estonia

• Finland

• France

• Germany

• Greece

• Hungary

• Ireland

• Iceland

• Italy

• Israel

• Kazakhstan

• Latvia

• Lithuania

• Luxembourg

• Moldova

• Monaco

• Netherlands

• Norway

• Poland

• Portugal

• Romania

• Saudi Arabia

• Serbia

• Slovakia

• Slovenia

• South Africa

• Spain

• Sweden

• Switzerland

• Turkiye

• Ukraine

• United Arab Emirates

• United Kingdom

classmethod from_bank_code(country_code: str, bank_code: str) → BIC

Create a new BIC object from country-code and domestic bank-code.

Examples

>>> bic = BIC.from_bank_code('DE', '20070000')
>>> bic.country_code
'DE'
>>> bic.bank_code
'DEUT'
>>> bic.location_code
'HH'

>>> BIC.from_bank_code('DE', '01010101')
Traceback (most recent call last):
...
InvalidBankCode: Unknown bank code '01010101' for country 'DE'

Parameters:

• country_code (str) – ISO 3166 alpha2 country-code.

• bank_code (str) – Country specific bank-code.

Returns:

a BIC object generated from the given country code and bank code.

Return type:

BIC

Raises:

InvalidBankCode – If the given bank code wasn’t found in the registry

Note

This currently only works for selected countries. Amongst them

• Austria

• Belgium

• Bulgaria

• Croatia

• Czech Republic

• Finland

• France

• Germany

• Great Britan

• Hungary

• Ireland

• Latvia

• Lithuania

• Netherlands

• Poland

• Romania

• Saudi Arabia

• Slovakia

• Slovenia

• Spain

• Sweden

• Switzerland

validate(enforce_swift_compliance: bool = False) → bool

Validate the structural integrity of this BIC.

This function will verify the correct length, structure and the existence of the country code.

Parameters:

enforce_swift_commpliance (bool) – If set to True the stricter SWIFT BIC policy is applied, which disallows numbers in the business prefix.

Note

You have to use the allow_invalid paramter when constructing the BIC-object to circumvent the implicit validation.

Raises:

• InvalidLength – If the BIC’s length is not 8 or 11 characters long.

• InvalidStructure – If the BIC contains unexpected characters.

• InvalidCountryCode – If the BIC’s country code is unknown.

property bank_code: str

The bank-code part of the BIC.

Type:

str

property bank_name: str | None

The name of the bank associated with the BIC.

Deprecated since version 2020.01.0: Use bank_names() instead.

Type:

str or None

property bank_names: list[str]

The name of the banks associated with the BIC.

Examples

>>> BIC('MARKDEF1100').bank_names
['Bundesbank']

Added in version 2020.01.0.

Type:

List[str]

property bank_short_name: str | None

The short name of the bank associated with the BIC.

Deprecated since version 2020.01.0: Use bank_short_names() instead.

Type:

str or None

property bank_short_names: list[str]

The short name of the banks associated with the BIC.

Examples

>>> BIC('MARKDEF1100').bank_short_names
['BBk Berlin']

Added in version 2020.01.0.

Type:

List[str]

property branch_code: str

The branch-code part of the BIC (if available)

Type:

str

property country: Data | None

The country this BIC is registered in.

Type:

Country

property country_bank_code: str | None

The country specific bank-code associated with the BIC.

Deprecated since version 2020.01.0: Use domestic_bank_codes() instead.

Type:

str or None

property country_code: str

The ISO 3166 alpha2 country-code.

Type:

str

property domestic_bank_codes: list[str]

The country specific bank-codes associated with the BIC.

Examples

>>> BIC('MARKDEF1100').domestic_bank_codes
['10000000']

Added in version 2020.01.0.

Type:

List[str]

property exists: bool

Indicates if the BIC is available in Schwifty’s registry.

Type:

bool

property formatted: str

The BIC separated in the blocks bank-, country- and location-code.

Examples

>>> BIC('MARKDEF1100').formatted
'MARK DE F1 100'

Type:

str

property is_valid: bool

Indicate if this is a valid BIC.

Note

You have to use the allow_invalid paramter when constructing the BIC-object to circumvent the implicit validation.

Examples

>>> BIC('FOOBARBAZ', allow_invalid=True).is_valid
False

Added in version 2020.08.1.

Type:

bool

property location_code: str

The location code of the BIC.

Type:

str

property type: str

Indicates the type of BIC.

This can be one of ‘testing’, ‘passive’, ‘reverse billing’ or ‘default’

Examples

>>> BIC('MARKDEF1100').type
'passive'

Returns:

The BIC type.

Return type:

str

Exceptions

exception schwifty.exceptions.GenerateRandomOverflowError

Indicates that during random entity generation no valid value could be found.

This could for example be the case if the national checksum digit does not compute for a randomly chosen account code.

exception schwifty.exceptions.InvalidAccountCode

Indicates that the account code has an invalid strucutre.

exception schwifty.exceptions.InvalidBBANChecksum

Indicates that the BBAN’s checksum is invalid.

exception schwifty.exceptions.InvalidBankCode

Indicates that the bank code has an invalid structure.

exception schwifty.exceptions.InvalidBranchCode

Indicates that the branch code has an invalid strucutre.

exception schwifty.exceptions.InvalidChecksumDigits

Indicates that the IBAN’s checksum is invalid.

exception schwifty.exceptions.InvalidCountryCode

Unknown country code in the input.

exception schwifty.exceptions.InvalidLength

Indicates that the length of the input does not match the specifcation.

exception schwifty.exceptions.InvalidStructure

Indicates a strctural error of the input (e.g. invalid characters).

exception schwifty.exceptions.SchwiftyException

Base exception of all schwifty related errors.