Developer Interface

IBAN

class schwifty.IBAN(code: str, **kwargs: Any)[source]

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'
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.

  • 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.

classmethod generate(country_code: str, bank_code: str, account_code: str, branch_code: str = '') IBAN[source]

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.

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.

validate(validate_bban: bool = False) bool[source]

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.

  • 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 customer specific account-code

Type:

str

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'

New 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'

New in version 2022.04.2.

Type:

str or None

property bban: str

The BBAN part of the IBAN.

Type:

str

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 or None

property checksum_digits: str

Two digit checksum of the IBAN.

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 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

New in version 2020.08.1.

Type:

bool

property numeric: int

A numeric represenation of the IBAN.

Type:

int

property spec: dict[str, Any]

The country specific IBAN specification.

Type:

dict

BIC

class schwifty.BIC(code: str, **kwargs: Any)[source]

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:

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][source]

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

  • 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

classmethod from_bank_code(country_code: str, bank_code: str) BIC[source]

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[source]

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:
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']

New 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']

New 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']

New 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

New 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.InvalidAccountCode[source]

Indicates that the account code has an invalid strucutre.

exception schwifty.exceptions.InvalidBBANChecksum[source]

Indicates that the BBAN’s checksum is invalid.

exception schwifty.exceptions.InvalidBankCode[source]

Indicates that the bank code has an invalid structure.

exception schwifty.exceptions.InvalidBranchCode[source]

Indicates that the branch code has an invalid strucutre.

exception schwifty.exceptions.InvalidChecksumDigits[source]

Indicates that the IBAN’s checksum is invalid.

exception schwifty.exceptions.InvalidCountryCode[source]

Unknown country code in the input.

exception schwifty.exceptions.InvalidLength[source]

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

exception schwifty.exceptions.InvalidStructure[source]

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

exception schwifty.exceptions.SchwiftyException[source]

Base exception of all schwifty related errors.