joonis Logo

Documentation fintech.sepa

SEPA module of the Python FinTech package.

This module defines functions and classes to work with SEPA.

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

The creditor account (read-only).

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

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

path

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

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.
class fintech.sepa.Mandate(path)

SEPA mandate class.

Initializes the SEPA mandate instance.

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

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

cid

The creditor id (read-only).

closed

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

created

The creation date (read-only).

creditor

The creditor account (read-only).

debtor

The debtor account (read-only).

executed

The last execution date (read-only).

first

Flag if this mandate is used the first time. If changed, attribute sequence_type is adjusted automatically.

is_valid()

Checks if this SEPA mandate is still valid.

last

Flag if this mandate is used the last time. If changed, attribute sequence_type is adjusted automatically.

modified

The last modification date (read-only).

mref

The mandate reference (read-only).

pdf_path

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

recurrent

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

sequence_type

The sequence type of this mandate. A value of OOFF, FRST, FNAL or RCUR. If changed, the attributes first and last are adjusted automatically.

signed

The date of signature (read-only).

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).
bic

The BIC of this account (read-only).

cid

The creditor id of the account holder.

city

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

country

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

iban

The IBAN of this account (read-only).

mandate

The assigned mandate (read-only).

name

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

postcode

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

set_creditor_id(cid)

Sets the creditor id of the account holder, required by SEPA direct debit documents and the MandateManager.

set_mandate(mref, signed, first, last)

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.
  • first – Flag if this mandate is used the first time.
  • last – Flag if this mandate is used the last time.
Returns:

A Mandate object.

set_ultimate_name(name)

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

street

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

ultimate_name

The ultimate name used for SEPA transactions.

class fintech.sepa.SEPATransaction

The SEPATransaction class

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

account

The remote account (read-only).

amount

The transaction amount in EUR (read-only).

due_date

The appointed due date (read-only).

eref

The end-to-end reference EREF (read-only).

ext_purpose

The external purpose code (read-only).

id

The unique id of this transaction (read-only).

kref

The customer reference KREF (read-only).

purpose

The transaction purpose (read-only).

ultimate_name

The ultimate name of the local account (read-only).

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

SEPACreditTransfer class

Initializes the SEPA credit transfer instance.

Parameters:
  • account – The debtor account.
  • type – The credit transfer priority (NORM or HIGH).
  • 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. See module attribute CATEGORY_PURPOSE_CODES.
  • scheme – The PAIN scheme of the document. If not specified, the scheme is set to pain.001.003.03 if the local account is originated in Germany, otherwise it is set to pain.001.001.03.
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 creditor account.
  • amount (float) – The transaction amount in EUR.
  • purpose – The transaction purpose text.
  • eref – The end-to-end reference (optional).
  • ext_purpose – The SEPA external purpose code (optional). See module attribute EXTERNAL_PURPOSE_CODES.
  • 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.

batch

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

cat_purpose

The category purpose (read-only).

cutoff

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

message_id

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

pain_scheme

The PAIN scheme version (read-only).

render()

Renders the SEPACreditTransfer document and returns it as XML.

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.

type

The credit transfer priority type (read-only).

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

SEPADirectDebit class

Initializes the SEPA credit transfer instance.

Parameters:
  • account – The creditor account with an appointed creditor id.
  • type – The direct debit type (CORE, COR1 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. See module attribute CATEGORY_PURPOSE_CODES.
  • scheme – The PAIN scheme of the document. If not specified, the scheme is set to pain.008.003.02 if the local account is originated in Germany, otherwise it is set to pain.008.001.02.
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 debtor account with a valid mandate.
  • amount (float) – The transaction amount in EUR.
  • purpose – The transaction purpose text.
  • eref – The end-to-end reference (optional).
  • ext_purpose – The SEPA external purpose code (optional). See module attribute EXTERNAL_PURPOSE_CODES.
  • 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.

batch

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

cat_purpose

The category purpose (read-only).

cutoff

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

message_id

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

pain_scheme

The PAIN scheme version (read-only).

render()

Renders the SEPADirectDebit document and returns it as XML.

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.

type

The direct debit type (read-only).

Examples

Simple SEPA Credit Transfer (pain.001)

from fintech.sepa import Account, SEPACreditTransfer

# Create the debtor account from an IBAN
debtor = Account('DE89370400440532013000', 'Max Mustermann')
# Create the creditor account from a tuple (IBAN, BIC)
creditor = Account(('AT611904300234573201', 'BKAUATWW'), 'Maria Musterfrau')
# Create a SEPACreditTransfer instance
sct = SEPACreditTransfer(debtor)
# Add the transaction
trans = sct.add_transaction(creditor, 10.00, 'Purpose')
# Render the SEPA document
print sct.render()

Simple SEPA Direct Debit (pain.008)

from fintech.sepa import Account, SEPADirectDebit

# Create the creditor account from a tuple (ACCOUNT, BANKCODE)
creditor = Account(('532013000', '37040044'), 'Max Mustermann')
# Assign the creditor id
creditor.set_creditor_id('DE98ZZZ09999999999')
# Create the debtor account from a tuple (IBAN, BIC)
debtor = Account(('AT611904300234573201', 'BKAUATWW'), 'Maria Musterfrau')
# For a SEPA direct debit a valid mandate is required
debtor.set_mandate(mref='M00123456', signed='2014-02-01', first=True, last=False)
# Create a SEPADirectDebit instance of type CORE
sdd = SEPADirectDebit(creditor, 'CORE')
# Add the transaction
trans = sdd.add_transaction(debtor, 10.00, 'Purpose')
# Render the SEPA document
print sdd.render()

Can I
  help you?


Just drop me a line at
giraffe@joonis.de