English Deutsch

Documentation fintech.sepa

SEPA module of the Python FinTech package.

This module defines functions and classes to work with SEPA.

Index
class fintech.sepa.Account(iban, name, country=None, city=None, postcode=None, street=None)

Account class

Initializes the account instance.

Parameters
  • iban – Either the IBAN or a 2-tuple in the form of either (IBAN, BIC) or (ACCOUNT_NUMBER, BANK_CODE). The latter will be converted to the corresponding IBAN automatically. An IBAN is checked for validity.
  • name – The name of the account holder.
  • country – The country (ISO-3166 ALPHA 2) of the account holder (optional).
  • city – The city of the account holder (optional).
  • postcode – The postcode of the account holder (optional).
  • street – The street of the account holder (optional).
property address

Tuple of unstructured address lines (read-only).

property bic

The BIC of this account (read-only).

property cid

The creditor id of the account holder (readonly).

property city

The city of the account holder (read-only).

property country

The country of the account holder (read-only).

property cuc

The CBI unique code (CUC) of the account holder (readonly).

property iban

The IBAN of this account (read-only).

is_sepa()

Checks if this account seems to be valid within the Single Euro Payments Area. (added in v6.2.0)

property mandate

The assigned mandate (read-only).

property name

The name of the account holder (read-only).

property postcode

The postcode of the account holder (read-only).

set_mandate(mref, signed, recurrent=False)

Sets the SEPA mandate for this account.

Parameters
  • mref – The mandate reference.
  • signed – The date of signature. Can be a date object or an ISO8601 formatted string.
  • recurrent – Flag whether this is a recurrent mandate or not.
Returns
A Mandate object.
set_originator_id(cid=None, cuc=None)

Sets the originator id of the account holder (new in v6.1.1).

Parameters
  • cid – The SEPA creditor id. Required for direct debits and in some countries also for credit transfers.
  • cuc – The CBI unique code (only required in Italy).
set_ultimate_name(name)

Sets the ultimate name used for SEPA transactions and by the MandateManager.

property street

The street of the account holder (read-only).

property ultimate_name

The ultimate name used for SEPA transactions.

class fintech.sepa.Amount(value, currency=None)

The Amount class with an integrated currency converter.

Arithmetic operations can be performed directly on this object.

Initializes the Amount instance.

Parameters
  • value – The amount value.
  • currency – An ISO-4217 currency code. If not specified, it is set to the value of the class attribute default_currency which is initially set to EUR.
convert(currency)

Converts the amount to another currency on the bases of the current exchange rates provided by the European Central Bank. The exchange rates are automatically updated once a day and cached in memory for further usage.

Parameters
currency – The ISO-4217 code of the target currency.
Returns
An Amount object in the requested currency.
property currency

The ISO-4217 currency code.

property decimals

The number of decimal places (at least 2). Use the built-in round to adjust the decimal places.

classmethod update_exchange_rates()

Updates the exchange rates based on the data provided by the European Central Bank and stores it in the class attribute exchange_rates. Usually it is not required to call this method directly, since it is called automatically by the method convert().

Returns
A boolean flag whether updated exchange rates were available or not.
property value

The amount value of type decimal.Decimal.

class fintech.sepa.SEPATransaction(*args, **kwargs)

The SEPATransaction class

This class cannot be instantiated directly. An instance is returned by the method add_transaction() of a SEPA document instance or by the iterator of a CAMTDocument instance.

If it is a batch of other transactions, the instance can be treated as an iterable over all underlying transactions.

property address

A tuple which holds the address of the remote account holder.

property amount

The transaction amount of type Amount. Debits are always signed negative.

property bank_reference

The bank reference, used to uniquely identify a transaction.

property batch

Flag which indicates a batch transaction.

property bic

The BIC of the remote account (BIC).

property camt_reference

The reference to a CAMT file.

property cheque

The cheque number.

property classification

The transaction classification. For German banks it is a tuple in the form of (SWIFTCODE, GVC, PRIMANOTA, TEXTKEY), for Frensh banks a tuple in the form of (DOMAINCODE, FAMILYCODE, SUBFAMILYCODE, TRANSACTIONCODE), otherwise a plain string.

property country

The country of the remote account holder.

property date

The booking date or appointed due date.

property eref

The end-to-end reference (EREF).

get_account()

Returns an Account instance of the remote account.

property iban

The IBAN of the remote account (IBAN).

property info

The transaction information (BOOKINGTEXT).

property kref

The id of the logical PAIN file (KREF).

property mref

The mandate reference (MREF).

property msgid

The message id of the physical PAIN file.

property name

The name of the remote account holder.

property originator_id

The creditor or debtor id of the remote account (CRED/DEBT).

property purpose

A tuple of the transaction purpose (SVWZ).

property purpose_code

The external purpose code (PURP).

property return_info

A tuple of return code and reason.

property reversal

The reversal indicator.

property status

The transaction status. A value of INFO, PDNG or BOOK.

property ultimate_name

The ultimate name of the remote account (ABWA/ABWE).

property valuta

The value date.

class fintech.sepa.SEPACreditTransfer(account, type='NORM', cutoff=14, batch=True, cat_purpose=None, scheme=None, currency=None)

SEPACreditTransfer class

Initializes the SEPA credit transfer instance.

Parameters
  • account – The local debtor account.
  • type – The credit transfer priority (NORM, HIGH, URGP or INST). At time Instant Payments are only supported with scheme pain.001.001.03 (new in v6.2.0: INST, new in v7.0.0: URGP)
  • cutoff – The cut-off time of the debtor’s bank.
  • batch – Flag whether SEPA batch mode is enabled or not.
  • cat_purpose – The SEPA category purpose code. This code is used for special treatments by the local bank and is not forwarded to the remote bank. See module attribute CATEGORY_PURPOSE_CODES for possible values.
  • scheme – The PAIN scheme of the document. If not specified, the scheme is set to pain.001.001.03. In Switzerland it is set to pain.001.001.03.ch.02, in Italy to CBIPaymentRequest.00.04.00.
  • currency – The ISO-4217 code of the currency to use. It must match with the currency of the local account. If not specified, it defaults to the currency of the country the local IBAN belongs to.
property account

The local account (read-only).

add_transaction(account, amount, purpose, eref=None, ext_purpose=None, due_date=None)

Adds a transaction to the SEPACreditTransfer document. If scl_check is set to True, it is verified that the transaction can be routed to the target bank.

Parameters
  • account – The remote creditor account.
  • amount – The transaction amount as floating point number or an instance of Amount. In the latter case the currency must match the currency of the document.
  • purpose – The transaction purpose text. If the value matches a valid ISO creditor reference number (starting with “RF…”), it is added as a structured reference. For other structured references a tuple can be passed in the form of (REFERENCE_NUMBER, PURPOSE_TEXT).
  • eref – The end-to-end reference (optional).
  • ext_purpose – The SEPA external purpose code (optional). This code is forwarded to the remote bank and the account holder. See module attribute EXTERNAL_PURPOSE_CODES for possible values.
  • due_date – The due date. If it is an integer or None, the next possible date is calculated starting from today plus the given number of days (considering holidays and the given cut-off time). If it is a date object or an ISO8601 formatted string, this date is used without further validation.
Returns
A SEPATransaction instance.
property batch

Flag if batch mode is enabled (read-only).

property cat_purpose

The category purpose (read-only).

property currency

The ISO-4217 currency code (read-only).

property cutoff

The cut-off time of the local bank (read-only).

property message_id

The message id of this document (read-only).

new_batch(kref=None)

After calling this method additional transactions are added to a new batch (PmtInf block). This could be useful if you want to divide transactions into different batches with unique KREF ids.

Parameters
kref – It is possible to set a custom KREF (PmtInfId) for the new batch (new in v7.2). Be aware that KREF ids should be unique over time and that all transactions must be grouped by particular SEPA specifications (date, sequence type, etc.) into separate batches. This is done automatically if you do not pass a custom KREF.
render()

Renders the SEPACreditTransfer document and returns it as XML.

property scheme

The document scheme version (read-only).

property scl_check

Flag whether remote accounts should be verified against the SEPA Clearing Directory or not. The initial value is set to True if the kontocheck library is available and the local account is originated in Germany, otherwise it is set to False.

send(ebics_client, use_ful=None)

Sends the SEPA document using the passed EBICS instance.

Parameters
Returns
The EBICS order id.
property type

The credit transfer priority type (read-only).

class fintech.sepa.SEPADirectDebit(account, type='CORE', cutoff=36, batch=True, cat_purpose=None, scheme=None, currency=None)

SEPADirectDebit class

Initializes the SEPA direct debit instance.

Parameters
  • account – The local creditor account with an appointed creditor id.
  • type – The direct debit type (CORE or B2B).
  • cutoff – The cut-off time of the creditor’s bank.
  • batch – Flag if SEPA batch mode is enabled or not.
  • cat_purpose – The SEPA category purpose code. This code is used for special treatments by the local bank and is not forwarded to the remote bank. See module attribute CATEGORY_PURPOSE_CODES for possible values.
  • scheme – The PAIN scheme of the document. If not specified, the scheme is set to pain.008.001.02. In Switzerland it is set to pain.008.001.02.ch.01, in Italy to CBISDDReqLogMsg.00.01.00.
  • currency – The ISO-4217 code of the currency to use. It must match with the currency of the local account. If not specified, it defaults to the currency of the country the local IBAN belongs to.
property account

The local account (read-only).

add_transaction(account, amount, purpose, eref=None, ext_purpose=None, due_date=None)

Adds a transaction to the SEPADirectDebit document. If scl_check is set to True, it is verified that the transaction can be routed to the target bank.

Parameters
  • account – The remote debtor account with a valid mandate.
  • amount – The transaction amount as floating point number or an instance of Amount. In the latter case the currency must match the currency of the document.
  • purpose – The transaction purpose text. If the value matches a valid ISO creditor reference number (starting with “RF…”), it is added as a structured reference. For other structured references a tuple can be passed in the form of (REFERENCE_NUMBER, PURPOSE_TEXT).
  • eref – The end-to-end reference (optional).
  • ext_purpose – The SEPA external purpose code (optional). This code is forwarded to the remote bank and the account holder. See module attribute EXTERNAL_PURPOSE_CODES for possible values.
  • due_date – The due date. If it is an integer or None, the next possible date is calculated starting from today plus the given number of days (considering holidays, the lead time and the given cut-off time). If it is a date object or an ISO8601 formatted string, this date is used without further validation.
Returns
A SEPATransaction instance.
property batch

Flag if batch mode is enabled (read-only).

property cat_purpose

The category purpose (read-only).

property currency

The ISO-4217 currency code (read-only).

property cutoff

The cut-off time of the local bank (read-only).

property message_id

The message id of this document (read-only).

new_batch(kref=None)

After calling this method additional transactions are added to a new batch (PmtInf block). This could be useful if you want to divide transactions into different batches with unique KREF ids.

Parameters
kref – It is possible to set a custom KREF (PmtInfId) for the new batch (new in v7.2). Be aware that KREF ids should be unique over time and that all transactions must be grouped by particular SEPA specifications (date, sequence type, etc.) into separate batches. This is done automatically if you do not pass a custom KREF.
render()

Renders the SEPADirectDebit document and returns it as XML.

property scheme

The document scheme version (read-only).

property scl_check

Flag whether remote accounts should be verified against the SEPA Clearing Directory or not. The initial value is set to True if the kontocheck library is available and the local account is originated in Germany, otherwise it is set to False.

send(ebics_client, use_ful=None)

Sends the SEPA document using the passed EBICS instance.

Parameters
Returns
The EBICS order id.
property type

The direct debit type (read-only).

class fintech.sepa.CAMTDocument(xml, camt54=None)

The CAMTDocument class is used to parse CAMT52, CAMT53 or CAMT54 documents. An instance can be treated as an iterable over its transactions, each represented as an instance of type SEPATransaction.

Note: If orders were submitted in batch mode, there are three methods to resolve the underlying transactions. Either (A) directly within the CAMT52/CAMT53 document, (B) within a separate CAMT54 document or (C) by a reference to the originally transfered PAIN message. The applied method depends on the bank (method B is most commonly used).

Initializes the CAMTDocument instance.

Parameters
  • xml – The XML string of a CAMT document to be parsed (either CAMT52, CAMT53 or CAMT54).
  • camt54 – In case xml is a CAMT52 or CAMT53 document, an additional CAMT54 document or a sequence of such documents can be passed which are automatically merged with the corresponding batch transactions.
property balance_close

The closing balance of type Amount (read-only).

property balance_open

The opening balance of type Amount (read-only).

property bic

The local BIC (read-only).

property created

The date of creation (read-only).

property currency

The currency of the account (read-only).

property date_from

The start date (read-only).

property date_to

The end date (read-only).

property iban

The local IBAN (read-only).

property info

Some info text about the document (read-only).

property message_id

The message id (read-only).

property name

The name of the account holder (read-only).

property reference_id

A unique reference number (read-only).

property sequence_id

The statement sequence number (read-only).

property type

The CAMT type, eg. camt.053.001.02 (read-only).

class fintech.sepa.Mandate(path)

SEPA mandate class.

Initializes the SEPA mandate instance.

Parameters
path – The path to a SEPA PDF file.
property b2b

Flag if it is a B2B mandate (read-only).

property cid

The creditor id (read-only).

property closed

Flag if the mandate is closed (read-only).

property created

The creation date (read-only).

property creditor

The creditor account (read-only).

property debtor

The debtor account (read-only).

property executed

The last execution date (read-only).

is_valid()

Checks if this SEPA mandate is still valid.

property modified

The last modification date (read-only).

property mref

The mandate reference (read-only).

property pdf_path

The path to the PDF file (read-only).

property recurrent

Flag whether this mandate is recurrent or not.

property signed

The date of signature (read-only).

class fintech.sepa.MandateManager(path, account)

A MandateManager manages all SEPA mandates that are required for SEPA direct debit transactions.

It stores all mandates as PDF files in a given directory.

Warning

The MandateManager is still BETA. Don’t use for production!

Initializes the mandate manager instance.

Parameters
  • path – The path to a directory where all mandates are stored. If it does not exist it will be created.
  • account – The creditor account with the full address and an appointed creditor id.
property account

The creditor account (read-only).

add_mandate(account, mref=None, signature=None, recurrent=True, b2b=False, lang=None)

Adds a new SEPA mandate and creates the corresponding PDF file. If scl_check is set to True, it is verified that a direct debit transaction can be routed to the target bank.

Parameters
  • account – The debtor account with the full address.
  • mref – The mandate reference. If not specified, a new reference number will be created.
  • signature – The signature which must be the full name of the account holder. If given, the mandate is marked as signed. Otherwise the method sign_mandate() must be called before the mandate can be used for a direct debit.
  • recurrent – Flag if it is a recurrent mandate or not.
  • b2b – Flag if it is a B2B mandate or not.
  • lang – ISO 639-1 language code of the mandate to create. Defaults to the language of the account holder’s country.
Returns
The created or passed mandate reference.
archive_mandates(zipfile)

Archives all closed SEPA mandates.

Currently not implemented!

Parameters
zipfile – The path to a zip file.
get_account(mref)

Get the debtor account of a SEPA mandate.

Parameters
mref – The mandate reference.
Returns
A Account object.
get_mandate(mref)

Get a stored SEPA mandate.

Parameters
mref – The mandate reference.
Returns
A Mandate object.
get_pdf(mref, save_as=None)

Get the PDF document of a SEPA mandate.

All SEPA meta data is removed from the PDF.

Parameters
  • mref – The mandate reference.
  • save_as – If given, it must be the destination path where the PDF file is saved.
Returns
The raw PDF data.
property path

The path where all mandates are stored (read-only).

property scl_check

Flag whether remote accounts should be verified against the SEPA Clearing Directory or not. The initial value is set to True if the kontocheck library is available and the local account is originated in Germany, otherwise it is set to False.

sign_mandate(document, mref=None, signed=None)

Updates a SEPA mandate with a signed document.

Parameters
  • document – The path to the signed document, which can be an image or PDF file.
  • mref – The mandate reference. If not specified and document points to an image, the image is scanned for a Code39 barcode which represents the mandate reference.
  • signed – The date of signature. If not specified, the current date is used.
Returns
The mandate reference.
update_mandate(mref, executed=None, closed=None)

Updates the SEPA meta data of a mandate.

Parameters
  • mref – The mandate reference.
  • executed – The last execution date. Can be a date object or an ISO8601 formatted string.
  • closed – Flag if this mandate is closed.
Share it Facebook Twitter Email AddThis