mt940.tags module

The MT940 format is a standard for bank account statements. It is used by many banks in Europe and is based on the SWIFT MT940 format.

The MT940 tags are:

Tag

Description

:13:

Date/Time indication at which the report was created

:20:

Transaction Reference Number

:21:

Related Reference Number

:25:

Account Identification

:28:

Statement Number

:34:

The floor limit for debit and credit

:60F:

Opening Balance

:60M:

Intermediate Balance

:60E:

Closing Balance

:61:

Statement Line

:62:

Closing Balance

:62M:

Intermediate Closing Balance

:62F:

Final Closing Balance

:64:

Available Balance

:65:

Forward Available Balance

:86:

Transaction Information

:90:

Total number and amount of debit entries

:NS:

Bank specific Non-swift extensions containing extra information

Format

Sources:

The pattern for the tags use the following syntax:

[] = optional
! = fixed length
a = Text
x = Alphanumeric, seems more like text actually. Can include special
    characters (slashes) and whitespace as well as letters and numbers
d = Numeric separated by decimal (usually comma)
c = Code list value
n = Numeric
class mt940.tags.Tag(*args, **kwargs)[source]

Bases: object

Base Tag class for parsing and handling MT940 tag contents.

Parameters:
Return type:

Tag

id: str | int = 0
RE_FLAGS = 98
scope

alias of Transactions

pattern: str
name: str
slug: str
logger: Logger
parse(transactions, value)[source]

Parses the given value using the Tag’s pattern.

Parameters:

  • transactions (Transactions) – The transactions model instance.

  • value (str) – The string value to parse.

Returns:

A dictionary of matched group values.

Raises:

RuntimeError – If the value does not match the tag’s pattern.

Return type:

dict[str, str | None]

class mt940.tags.DateTimeIndication(*args, **kwargs)[source]

Bases: Tag

Date/Time indication at which the report was created

Pattern: 6!n4!n1! x4!n

Parameters:
Return type:

Tag

id: str | int = 13
pattern: str = '^\n    (?P<year>\\d{2})\n    (?P<month>\\d{2})\n    (?P<day>\\d{2})\n    (?P<hour>\\d{2})\n    (?P<minute>\\d{2})\n    (\\+(?P<offset>\\d{4})|)\n    '
logger: Logger = <Logger mt940.tags.DateTimeIndication (INFO)>
name: str = 'DateTimeIndication'
slug: str = 'date_time_indication'
class mt940.tags.TransactionReferenceNumber(*args, **kwargs)[source]

Bases: Tag

Transaction reference number

Pattern: 16x

Parameters:
Return type:

Tag

id: str | int = 20
pattern: str = '(?P<transaction_reference>.{0,16})'
logger: Logger = <Logger mt940.tags.TransactionReferenceNumber (INFO)>
name: str = 'TransactionReferenceNumber'
slug: str = 'transaction_reference_number'
class mt940.tags.RelatedReference(*args, **kwargs)[source]

Bases: Tag

Related reference

Pattern: 16x

Parameters:
Return type:

Tag

id: str | int = 21
pattern: str = '(?P<related_reference>.{0,16})'
logger: Logger = <Logger mt940.tags.RelatedReference (INFO)>
name: str = 'RelatedReference'
slug: str = 'related_reference'
class mt940.tags.AccountIdentification(*args, **kwargs)[source]

Bases: Tag

Account identification

Pattern: 35x

Parameters:
Return type:

Tag

id: str | int = 25
pattern: str = '(?P<account_identification>.{0,35})'
logger: Logger = <Logger mt940.tags.AccountIdentification (INFO)>
name: str = 'AccountIdentification'
slug: str = 'account_identification'
class mt940.tags.StatementNumber(*args, **kwargs)[source]

Bases: Tag

Statement number / sequence number

Pattern: 5n[/5n]

Parameters:
Return type:

Tag

id: str | int = 28
pattern: str = '\n    (?P<statement_number>\\d{1,5})  # 5n\n    (?:/?(?P<sequence_number>\\d{1,5}))?  # [/5n]\n    $'
logger: Logger = <Logger mt940.tags.StatementNumber (INFO)>
name: str = 'StatementNumber'
slug: str = 'statement_number'
class mt940.tags.FloorLimitIndicator(*args, **kwargs)[source]

Bases: Tag

Floor limit indicator indicates the minimum value reported for debit and credit amounts

Pattern: :34F:GHSC0,00

Parameters:
Return type:

Tag

id: str | int = 34
pattern: str = '^\n    (?P<currency>[A-Z]{3})  # 3!a Currency\n    (?P<status>[DC ]?)  # 2a Debit/Credit Mark\n    (?P<amount>[0-9,]{0,16})  # 15d Amount (includes decimal sign, so 16)\n    $'
logger: Logger = <Logger mt940.tags.FloorLimitIndicator (INFO)>
name: str = 'FloorLimitIndicator'
slug: str = 'floor_limit_indicator'
class mt940.tags.NonSwift(*args, **kwargs)[source]

Bases: Tag

Non-swift extension for MT940 containing extra information. The actual definition is not consistent between banks so the current implementation is a tad limited. Feel free to extend the implementation and create a pull request with a better version :)

It seems this could be anything so we’ll have to be flexible about it.

Pattern: 2!n35x | *x

Parameters:
Return type:

Tag

scope

alias of TransactionsAndTransaction

id: str | int = 'NS'
pattern: str = '\n    (?P<non_swift>\n        (\n            (\\d{2}.{0,})\n            (\\n\\d{2}.{0,})*\n        )|(\n            [^\\n]*\n        )\n    )\n    $'
sub_pattern = '\n    (?P<ns_id>\\d{2})(?P<ns_data>.{0,})\n    '
sub_pattern_m = re.compile('\n    (?P<ns_id>\\d{2})(?P<ns_data>.{0,})\n    ', re.IGNORECASE|re.VERBOSE)
logger: Logger = <Logger mt940.tags.NonSwift (INFO)>
name: str = 'NonSwift'
slug: str = 'non_swift'
class mt940.tags.BalanceBase(*args, **kwargs)[source]

Bases: Tag

Balance base

Pattern: 1!a6!n3!a15d

Parameters:
Return type:

Tag

pattern: str = '^\n    (?P<status>[DC])  # 1!a Debit/Credit\n    (?P<year>\\d{2})  # 6!n Value Date (YYMMDD)\n    (?P<month>\\d{2})\n    (?P<day>\\d{2})\n    (?P<currency>.{3})  # 3!a Currency\n    (?P<amount>[0-9,]{0,16})  # 15d Amount (includes decimal sign, so 16)\n    '
class mt940.tags.OpeningBalance(*args, **kwargs)[source]

Bases: BalanceBase

Opening balance (:60:).

Parameters:
Return type:

Tag

id: str | int = 60
logger: Logger = <Logger mt940.tags.OpeningBalance (INFO)>
name: str = 'OpeningBalance'
slug: str = 'opening_balance'
class mt940.tags.FinalOpeningBalance(*args, **kwargs)[source]

Bases: BalanceBase

Final opening balance (:60F:).

Parameters:
Return type:

Tag

id: str | int = '60F'
logger: Logger = <Logger mt940.tags.FinalOpeningBalance (INFO)>
name: str = 'FinalOpeningBalance'
slug: str = 'final_opening_balance'
class mt940.tags.IntermediateOpeningBalance(*args, **kwargs)[source]

Bases: BalanceBase

Intermediate opening balance (:60M:).

Parameters:
Return type:

Tag

id: str | int = '60M'
logger: Logger = <Logger mt940.tags.IntermediateOpeningBalance (INFO)>
name: str = 'IntermediateOpeningBalance'
slug: str = 'intermediate_opening_balance'
class mt940.tags.Statement(*args, **kwargs)[source]

Bases: Tag

The MT940 Tag 61 provides information about a single transaction that has taken place on the account. Each transaction is identified by a unique transaction reference number (Tag 20) and is described in the Statement Line (Tag 61).

Pattern: 6!n[4!n]2a[1!a]15d1!a3!c23x[//16x]

The fields are:

  • value_date: transaction date (YYMMDD)

  • entry_date: Optional 4-digit month value and 2-digit day value of the entry date (MMDD) or 4 whitespace characters (some banks insert spaces here)

  • funds_code: Optional 1-character code indicating the funds type ( the third character of the currency code if needed)

  • amount: 15-digit value of the transaction amount, including commas for decimal separation

  • transaction_type: Optional 4-character transaction type identification code starting with a letter followed by alphanumeric characters and spaces

  • customer_reference: Optional 16-character customer reference, excluding any bank reference

  • bank_reference: Optional 23-character bank reference starting with “//”

  • supplementary_details: Optional 34-character supplementary details about the transaction.

The Tag 61 can occur multiple times within an MT940 file, with each occurrence representing a different transaction.

Parameters:
Return type:

Tag

id: str | int = 61
scope

alias of Transaction

pattern: str = '^\n    (?P<year>\\d{2})  # 6!n Value Date (YYMMDD)\n    (?P<month>\\d{2})\n    (?P<day>\\d{2})\n    (?P<entry_month>\\d{2}|\\s{2})?  # [4!n] Entry Date (MMDD)\n    (?P<entry_day>\\d{2}|\\s{2})?\n    (?P<status>R?[DC])  # 2a Debit/Credit Mark\n    (?P<funds_code>[A-Z])? # [1!a] Funds Code (3rd character of the currency\n                            # code, if needed)\n    [\\n ]?\n    (?P<amount>[\\d,]{1,15})  # 15d Amount\n    (?P<id>[A-Z][A-Z0-9 ]{3})?\n    (?P<customer_reference>((?!//)[^\\n]){0,16})\n    (//(?P<bank_reference>.{0,23}))?\n    # Supplementary details: the SWIFT spec caps this at 34x, but some banks\n    # (e.g. Wise, issue #117) send more, so the length limit is relaxed. This\n    # only ever turns a previous parse error into a successful parse.\n    (\\n?(?P<extra_details>.*))?\n    $'
logger: Logger = <Logger mt940.tags.Statement (INFO)>
name: str = 'Statement'
slug: str = 'statement'
class mt940.tags.StatementASNB[source]

Bases: Statement

From: https://www.sepaforcorporates.com/swift-for-corporates

Pattern: 6!n[4!n]2a[1!a]15d1!a3!c34x[//16x] [34x]

But ASN bank puts the IBAN in the customer reference, which is according to Wikipedia at most 34 characters.

So this is the new pattern:

Pattern: 6!n[4!n]2a[1!a]15d1!a3!c34x[//16x] [34x]

Parameters:
Return type:

Tag

pattern: str = '^\n    (?P<year>\\d{2})  # 6!n Value Date (YYMMDD)\n    (?P<month>\\d{2})\n    (?P<day>\\d{2})\n    (?P<entry_month>\\d{2}|\\s{2})?\n    (?P<entry_day>\\d{2}|\\s{2})?\n    (?P<status>[A-Z]?[DC])\n    (?P<funds_code>[A-Z])?\n    \\n?\n    (?P<amount>[\\d,]{1,15})\n    (?P<id>[A-Z][A-Z0-9 ]{3})?\n    (?P<customer_reference>.{0,34})\n    (//(?P<bank_reference>.{0,16}))?\n    (\\n?(?P<extra_details>.{0,34}))?\n    $'
class mt940.tags.StatementGLS(*args, **kwargs)[source]

Bases: Statement

Statement variant for GLS / Atruvia banks (issue #111).

These banks send a customer reference longer than the SWIFT 16x cap, followed by the // bank-reference delimiter (e.g. ...DR20,NTRFBIPI-dvT1FzfMqvzF5HaU4oetlH7SGRkonU//2022070616391534000).

This is an opt-in tag because relaxing the default customer-reference length would change how banks that legitimately pack data after a 16x reference (e.g. Rabobank) are parsed. Enable it explicitly:

import mt940

gls = mt940.tags.StatementGLS()
mt940.parse(data, tags={gls.id: gls})
Parameters:
Return type:

Tag

pattern: str = '^\n    (?P<year>\\d{2})  # 6!n Value Date (YYMMDD)\n    (?P<month>\\d{2})\n    (?P<day>\\d{2})\n    (?P<entry_month>\\d{2}|\\s{2})?  # [4!n] Entry Date (MMDD)\n    (?P<entry_day>\\d{2}|\\s{2})?\n    (?P<status>R?[DC])  # 2a Debit/Credit Mark\n    (?P<funds_code>[A-Z])?\n    [\\n ]?\n    (?P<amount>[\\d,]{1,15})  # 15d Amount\n    (?P<id>[A-Z][A-Z0-9 ]{3})?\n    # Customer reference of any length, up to the // bank reference.\n    (?P<customer_reference>(?:(?!//)[^\\n])*)\n    (//(?P<bank_reference>.{0,23}))?\n    (\\n?(?P<extra_details>.*))?\n    $'
class mt940.tags.ClosingBalance(*args, **kwargs)[source]

Bases: BalanceBase

Closing balance (:62:).

Parameters:
Return type:

Tag

id: str | int = 62
logger: Logger = <Logger mt940.tags.ClosingBalance (INFO)>
name: str = 'ClosingBalance'
slug: str = 'closing_balance'
class mt940.tags.IntermediateClosingBalance(*args, **kwargs)[source]

Bases: ClosingBalance

Intermediate closing balance (:62M:).

Parameters:
Return type:

Tag

id: str | int = '62M'
logger: Logger = <Logger mt940.tags.IntermediateClosingBalance (INFO)>
name: str = 'IntermediateClosingBalance'
slug: str = 'intermediate_closing_balance'
class mt940.tags.FinalClosingBalance(*args, **kwargs)[source]

Bases: ClosingBalance

Final closing balance (:62F:).

Parameters:
Return type:

Tag

id: str | int = '62F'
logger: Logger = <Logger mt940.tags.FinalClosingBalance (INFO)>
name: str = 'FinalClosingBalance'
slug: str = 'final_closing_balance'
class mt940.tags.AvailableBalance(*args, **kwargs)[source]

Bases: BalanceBase

Available balance (:64:).

Parameters:
Return type:

Tag

id: str | int = 64
logger: Logger = <Logger mt940.tags.AvailableBalance (INFO)>
name: str = 'AvailableBalance'
slug: str = 'available_balance'
class mt940.tags.ForwardAvailableBalance(*args, **kwargs)[source]

Bases: BalanceBase

Forward available balance (:65:).

Parameters:
Return type:

Tag

id: str | int = 65
logger: Logger = <Logger mt940.tags.ForwardAvailableBalance (INFO)>
name: str = 'ForwardAvailableBalance'
slug: str = 'forward_available_balance'
class mt940.tags.TransactionDetails(*args, **kwargs)[source]

Bases: Tag

Transaction details

Pattern: 6x65x

Parameters:
Return type:

Tag

id: str | int = 86
scope

alias of Transaction

pattern: str = '\n    (?P<transaction_details>(([\\s\\S]{0,65}\\r?\\n?){0,8}[\\s\\S]{0,65}))\n    '
logger: Logger = <Logger mt940.tags.TransactionDetails (INFO)>
name: str = 'TransactionDetails'
slug: str = 'transaction_details'
class mt940.tags.SumEntries(*args, **kwargs)[source]

Bases: Tag

Number and Sum of debit Entries

Parameters:
Return type:

Tag

id: str | int = 90
pattern: str = '^\n    (?P<number>\\d*)\n    (?P<currency>.{3})  # 3!a Currency\n    (?P<amount>[\\d,]{1,15})  # 15d Amount\n    '
status: str
logger: Logger = <Logger mt940.tags.SumEntries (INFO)>
name: str = 'SumEntries'
slug: str = 'sum_entries'
class mt940.tags.SumDebitEntries(*args, **kwargs)[source]

Bases: SumEntries

Number and sum of debit entries (:90D:).

Parameters:
Return type:

Tag

status: str = 'D'
id: str | int = '90D'
logger: Logger = <Logger mt940.tags.SumDebitEntries (INFO)>
name: str = 'SumDebitEntries'
slug: str = 'sum_debit_entries'
class mt940.tags.SumCreditEntries(*args, **kwargs)[source]

Bases: SumEntries

Number and sum of credit entries (:90C:).

Parameters:
Return type:

Tag

status: str = 'C'
id: str | int = '90C'
logger: Logger = <Logger mt940.tags.SumCreditEntries (INFO)>
name: str = 'SumCreditEntries'
slug: str = 'sum_credit_entries'
class mt940.tags.Tags(*values)[source]

Bases: Enum

Registry of the built-in tag parsers, one instance per member.

DATE_TIME_INDICATION = <mt940.tags.DateTimeIndication object>
Parameters:
Return type:

dict[str, object]

TRANSACTION_REFERENCE_NUMBER = <mt940.tags.TransactionReferenceNumber object>
Parameters:
Return type:

dict[str, Any]

RELATED_REFERENCE = <mt940.tags.RelatedReference object>
Parameters:
Return type:

dict[str, Any]

ACCOUNT_IDENTIFICATION = <mt940.tags.AccountIdentification object>
Parameters:
Return type:

dict[str, Any]

STATEMENT_NUMBER = <mt940.tags.StatementNumber object>
Parameters:
Return type:

dict[str, Any]

OPENING_BALANCE = <mt940.tags.OpeningBalance object>
Parameters:
Return type:

dict[str, object]

INTERMEDIATE_OPENING_BALANCE = <mt940.tags.IntermediateOpeningBalance object>
Parameters:
Return type:

dict[str, object]

FINAL_OPENING_BALANCE = <mt940.tags.FinalOpeningBalance object>
Parameters:
Return type:

dict[str, object]

STATEMENT = <mt940.tags.Statement object>
Parameters:
Return type:

dict[str, object]

CLOSING_BALANCE = <mt940.tags.ClosingBalance object>
Parameters:
Return type:

dict[str, object]

INTERMEDIATE_CLOSING_BALANCE = <mt940.tags.IntermediateClosingBalance object>
Parameters:
Return type:

dict[str, object]

FINAL_CLOSING_BALANCE = <mt940.tags.FinalClosingBalance object>
Parameters:
Return type:

dict[str, object]

AVAILABLE_BALANCE = <mt940.tags.AvailableBalance object>
Parameters:
Return type:

dict[str, object]

FORWARD_AVAILABLE_BALANCE = <mt940.tags.ForwardAvailableBalance object>
Parameters:
Return type:

dict[str, object]

TRANSACTION_DETAILS = <mt940.tags.TransactionDetails object>
Parameters:
Return type:

dict[str, Any]

FLOOR_LIMIT_INDICATOR = <mt940.tags.FloorLimitIndicator object>
Parameters:
Return type:

dict[str, object]

NON_SWIFT = <mt940.tags.NonSwift object>
Parameters:
Return type:

dict[str, object]

SUM_ENTRIES = <mt940.tags.SumEntries object>
Parameters:
Return type:

dict[str, object]

SUM_DEBIT_ENTRIES = <mt940.tags.SumDebitEntries object>
Parameters:
Return type:

dict[str, object]

SUM_CREDIT_ENTRIES = <mt940.tags.SumCreditEntries object>
Parameters:
Return type:

dict[str, object]

mt940.tags.TAG_BY_ID = {'60F': <mt940.tags.FinalOpeningBalance object>, '60M': <mt940.tags.IntermediateOpeningBalance object>, '62F': <mt940.tags.FinalClosingBalance object>, '62M': <mt940.tags.IntermediateClosingBalance object>, '90C': <mt940.tags.SumCreditEntries object>, '90D': <mt940.tags.SumDebitEntries object>, 'NS': <mt940.tags.NonSwift object>, 13: <mt940.tags.DateTimeIndication object>, 20: <mt940.tags.TransactionReferenceNumber object>, 21: <mt940.tags.RelatedReference object>, 25: <mt940.tags.AccountIdentification object>, 28: <mt940.tags.StatementNumber object>, 34: <mt940.tags.FloorLimitIndicator object>, 60: <mt940.tags.OpeningBalance object>, 61: <mt940.tags.Statement object>, 62: <mt940.tags.ClosingBalance object>, 64: <mt940.tags.AvailableBalance object>, 65: <mt940.tags.ForwardAvailableBalance object>, 86: <mt940.tags.TransactionDetails object>, 90: <mt940.tags.SumEntries object>}

Mapping of tag id (int or str) to the tag instance that parses it.