joonis Logo

Dokumentation fintech.ebics

EBICS client module of the Python FinTech package.

This module defines functions and classes to work with EBICS.

Index
class fintech.ebics.EbicsKeyRing(keys, passphrase=None)

EBICS key ring representation

An EbicsKeyRing instance can hold sets of private user keys and/or public bank keys. Private user keys are always stored AES encrypted by the specified passphrase (derivated by PBKDF2). For each key file on disk or same key dictionary a singleton instance is created.

Initializes the EBICS key ring instance.

Parameters:
  • keys – The path to a key file or a dictionary of keys. If keys is a path and the key file does not exist, it will be created as soon as keys are added. If keys is a dictionary, all changes are applied to this dictionary and the caller is responsible to store the modifications. Key files from previous PyEBICS versions are automatically converted to a new format.
  • passphrase – The passphrase by which all private keys are encrypted/decrypted.
change_passphrase(passphrase)

Changes the passphrase by which all private keys are encrypted. The key ring is automatically updated and saved.

Parameters:passphrase – The new passphrase.
keyfile

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

pbkdf_iterations

The number of iterations to derivate the passphrase by the PBKDF2 algorithm. Initially it is set to a number that requires an approximate run time of 50 ms to perform the derivation function.

save(path=None)

Saves all keys to the file specified by path. Usually it is not necessary to call this method, since most modifications are stored automatically.

Parameters:path – The path of the key file. If path is not specified, the path of the current key file is used.
set_pbkdf_iterations(iterations=10000, duration=None)

Sets the number of iterations which is used to derivate the passphrase by the PBKDF2 algorithm. The optimal number depends on the performance of the underlying system and the use case.

Parameters:
  • iterations – The minimum number of iterations to set.
  • duration – The target run time in seconds to perform the derivation function. A higher value results in a higher number of iterations.
Returns:

The specified or calculated number of iterations, whatever is higher.

class fintech.ebics.EbicsBank(keyring, hostid, url)

EBICS bank representation

Initializes the EBICS bank instance.

Parameters:
  • keyring – An EbicsKeyRing instance.
  • hostid – The HostID of the bank.
  • url – The URL of the EBICS server.
activate_keys()

Activates the bank keys downloaded via EbicsClient.HPB().

export_keys()

Exports the bank keys in PEM format.

Returns:A dictionary with pairs of key version and PEM encoded public key.
hostid

The HostID of the bank (read-only).

keyring

The EbicsKeyRing instance (read-only).

url

The URL of the EBICS server (read-only).

class fintech.ebics.EbicsUser(keyring, partnerid, userid, systemid=None)

EBICS user representation

Initializes the EBICS user instance.

Parameters:
  • keyring – An EbicsKeyRing instance.
  • partnerid – The assigned PartnerID (Kunden-ID).
  • userid – The assigned UserID (Teilnehmer-ID).
  • systemid – The assigned SystemID (usually unused).
create_certificates(validity_period=5, **x509_dn)

Generates self-signed certificates for all keys and adds them to the key ring. The PyOpenSSL package is required to perform this method. May only be used for EBICS accounts whose key management is based on certificates (eg. French banks).

Parameters:
  • validity_period – The validity period in years.
  • **x509_dn

    Keyword arguments, collected in x509_dn, are used as Distinguished Names to create the self-signed certificates. Possible keyword arguments are:

    • commonName [CN]
    • organizationName [O]
    • organizationalUnitName [OU]
    • countryName [C]
    • stateOrProvinceName [ST]
    • localityName [L]
    • emailAddress
create_ini_letter(bankname, path=None, lang=None)

Creates the INI-letter as PDF document.

Parameters:
  • bankname – The name of the bank which is printed on the INI-letter as the recipient.
  • path – The destination path of the created PDF file. If path is not specified, the PDF will not be saved.
  • lang – ISO 639-1 language code of the INI-letter to create. Defaults to the system locale language.
Returns:

The PDF data as byte string if path is None.

create_keys(keyversion='A006', bitlength=2048)

Generates all three keys which are required for a new EBICS user. The key ring will be automatically updated and saved.

Parameters:
  • keyversion – The key version of the electronic signature. Supported versions are A005 (based on RSASSA-PKCS1-v1_5) and A006 (based on RSASSA-PSS).
  • bitlength – The bit length of the generated keys. The value must be between 1536 and 4096 (default is 2048).
export_certificates()

Exports the user certificates in PEM format.

Returns:A dictionary with pairs of key version and a list of PEM encoded certificates (the certificate chain).
export_keys(passphrase, pkcs=8)

Exports the user keys in encrypted PEM format.

Parameters:
  • passphrase – The passphrase by which all keys are encrypted. The encryption algorithm depends on the used cryptography library.
  • pkcs – The PKCS version. An integer of either 1 or 8.
Returns:

A dictionary with pairs of key version and PEM encoded private key.

import_certificates(**certs)

Imports certificates from a set of keyword arguments. The key ring is automatically updated and saved. May only be used for EBICS accounts whose key management is based on certificates (eg. French banks).

Parameters:**certs

Keyword arguments, collected in certs, represent the different certificates to import. The keyword name stands for the key version the certificate is assigned to. The corresponding keyword value can be a byte string of the certificate or a list of byte strings (the certificate chain). Each certificate can be either in format DER or PEM. At time the following keywords are supported: A006, A005, X002, E002.

import_keys(passphrase=None, **keys)

Imports private user keys from a set of keyword arguments. The key ring is automatically updated and saved.

Parameters:
  • passphrase – The passphrase if the keys are encrypted. At time only DES or 3TDES encrypted keys are supported.
  • **keys

    Additional keyword arguments, collected in keys, represent the different private keys to import. The keyword name stands for the key version and its value for the byte string of the corresponding key. The keys can be either in format DER or PEM (PKCS#1 or PKCS#8). At time the following keywords are supported:

    • A006: The signature key, based on RSASSA-PSS
    • A005: The signature key, based on RSASSA-PKCS1-v1_5
    • X002: The authentication key
    • E002: The encryption key
keyring

The EbicsKeyRing instance (read-only).

manual_approval

If uploaded orders are approved manually via accompanying document, this property must be set to True.

partnerid

The PartnerID of the EBICS account (read-only).

systemid

The SystemID of the EBICS account (read-only).

userid

The UserID of the EBICS account (read-only).

class fintech.ebics.EbicsClient(bank, user, version='H004')

Main EBICS client class.

Initializes the EBICS client instance.

Parameters:
  • bank – An instance of EbicsBank.
  • user – An instance of EbicsUser.
  • version – The EBICS protocol version (H003 or H004). It is strongly recommended to use version H004 (2.5). When using version H003 (2.4) the client is responsible to generate the required order ids, which must be implemented by your application.
C52(start=None, end=None, parsed=False)

Downloads Bank to Customer Account Reports (camt.52)

Parameters:
  • start – The start date of requested transactions. Can be a date object or an ISO8601 formatted string.
  • end – The end date of requested transactions. Can be a date object or an ISO8601 formatted string.
  • parsed – Flag whether the received XML documents should be parsed and returned as structures of dictionaries or not.
Returns:

A dictionary of either raw XML documents or structures of dictionaries.

C53(start=None, end=None, parsed=False)

Downloads Bank to Customer Statements (camt.53)

Parameters:
  • start – The start date of requested transactions. Can be a date object or an ISO8601 formatted string.
  • end – The end date of requested transactions. Can be a date object or an ISO8601 formatted string.
  • parsed – Flag whether the received XML documents should be parsed and returned as structures of dictionaries or not.
Returns:

A dictionary of either raw XML documents or structures of dictionaries.

C54(start=None, end=None, parsed=False)

Downloads Bank to Customer Debit Credit Notifications (camt.54)

Parameters:
  • start – The start date of requested transactions. Can be a date object or an ISO8601 formatted string.
  • end – The end date of requested transactions. Can be a date object or an ISO8601 formatted string.
  • parsed – Flag whether the received XML documents should be parsed and returned as structures of dictionaries or not.
Returns:

A dictionary of either raw XML documents or structures of dictionaries.

CCT(document)

Uploads a SEPA Credit Transfer document.

Parameters:document – The SEPA document to be uploaded either as a raw XML string or a fintech.sepa.SEPACreditTransfer object.
Returns:The id of the uploaded order (OrderID).
CD1(document)

Uploads a SEPA Direct Debit document of type COR1.

Parameters:document – The SEPA document to be uploaded either as a raw XML string or a fintech.sepa.SEPADirectDebit object.
Returns:The id of the uploaded order (OrderID).
CDB(document)

Uploads a SEPA Direct Debit document of type B2B.

Parameters:document – The SEPA document to be uploaded either as a raw XML string or a fintech.sepa.SEPADirectDebit object.
Returns:The id of the uploaded order (OrderID).
CDD(document)

Uploads a SEPA Direct Debit document of type CORE.

Parameters:document – The SEPA document to be uploaded either as a raw XML string or a fintech.sepa.SEPADirectDebit object.
Returns:The id of the uploaded order (OrderID).
CDZ(parsed=False)

Downloads Payment Status Report for Direct Debits.

Parameters:parsed – Flag whether the received XML documents should be parsed and returned as structures of dictionaries or not.
Returns:A dictionary of either raw XML documents or structures of dictionaries.
CRZ(parsed=False)

Downloads Payment Status Report for Credit Transfers.

Parameters:parsed – Flag whether the received XML documents should be parsed and returned as structures of dictionaries or not.
Returns:A dictionary of either raw XML documents or structures of dictionaries.
FDL(filetype, start=None, end=None, country=None)

Downloads a file in arbitrary format.

Parameters:
  • filetype – The requested file type.
  • start – The start date of requested transactions. Can be a date object or an ISO8601 formatted string.
  • end – The end date of requested transactions. Can be a date object or an ISO8601 formatted string.
  • country – The country code (ISO-3166 ALPHA 2) if the specified file type is country-specific.
Returns:

The requested file data.

FUL(filetype, data, country=None)

Uploads a file in arbitrary format.

Parameters:
  • filetype – The file type to upload.
  • data – The file data to upload.
  • country – The country code (ISO-3166 ALPHA 2) if the specified file type is country-specific.
Returns:

The order id (OrderID).

H3K()

Sends the public key of the electronic signature, the public authentication key and the encryption key based on certificates. At least the certificate for the signature key must be signed by a certification authority (CA) or the bank itself. Returns the assigned order id.

HAA(parsed=False)

Downloads the available order types.

Parameters:parsed – Flag whether the received XML document should be parsed and returned as a structure of dictionaries or not.
Returns:Either the raw XML document or a structure of dictionaries.
HAC(start=None, end=None, parsed=False)

Downloads the customer usage report in XML format.

Parameters:
  • start – The start date of requested processes. Can be a date object or an ISO8601 formatted string.
  • end – The end date of requested processes. Can be a date object or an ISO8601 formatted string.
  • parsed – Flag whether the received XML document should be parsed and returned as a structure of dictionaries or not.
Returns:

Either the raw XML document or a structure of dictionaries.

HCA(bitlength=2048)

Creates a new authentication and encryption key, transfers them to the bank and updates the user key ring.

Parameters:bitlength – The bit length of the generated keys. The value must be between 1536 and 4096 (default is 2048).
Returns:The assigned order id.
HCS(bitlength=2048, keyversion=None)

Creates a new signature, authentication and encryption key, transfers them to the bank and updates the user key ring. It acts like a combination of EbicsClient.PUB() and EbicsClient.HCA().

Parameters:
  • bitlength – The bit length of the generated keys. The value must be between 1536 and 4096 (default is 2048).
  • keyversion – The key version of the electronic signature. Supported versions are A005 (based on RSASSA-PKCS1-v1_5) and A006 (based on RSASSA-PSS). If not specified, the version of the current signature key is used.
Returns:

The assigned order id.

HEV()

Returns a dictionary of supported protocol versions.

HIA()

Sends the public authentication (X002) and encryption (E002) keys. Returns the assigned order id.

HKD(parsed=False)

Downloads the customer properties and settings.

Parameters:parsed – Flag whether the received XML document should be parsed and returned as a structure of dictionaries or not.
Returns:Either the raw XML document or a structure of dictionaries.
HPB()

Receives the public authentication (X002) and encryption (E002) keys from the bank.

The keys are added to the key file and must be activated by calling the method EbicsBank.activate_keys().

Returns:The string representation of the keys.
HPD(parsed=False)

Downloads the available bank parameters.

Parameters:parsed – Flag whether the received XML document should be parsed and returned as a structure of dictionaries or not.
Returns:Either the raw XML document or a structure of dictionaries.
HTD(parsed=False)

Downloads the user properties and settings.

Parameters:parsed – Flag whether the received XML document should be parsed and returned as a structure of dictionaries or not.
Returns:Either the raw XML document or a structure of dictionaries.
HVD(orderid, ordertype=None, partnerid=None, parsed=False)

This method is part of the distributed signature and downloads the signature status of a pending order.

Parameters:
  • orderid – The id of the order in question.
  • ordertype – The type of the order in question. If not specified, the corresponding order type is detected by calling the method EbicsClient.HVU().
  • partnerid – The partner id of the corresponding order. Defaults to the partner id of the current user.
  • parsed – Flag whether the received XML document should be parsed and returned as a structure of dictionaries or not.
Returns:

Either the raw XML document or a structure of dictionaries.

HVE(orderid, ordertype=None, hash=None, partnerid=None)

This method is part of the distributed signature and signs a pending order.

Parameters:
  • orderid – The id of the order in question.
  • ordertype – The type of the order in question. If not specified, the corresponding order type is detected by calling the method EbicsClient.HVZ().
  • hash – The base64 encoded hash of the order to be signed. If not specified, the corresponding hash is detected by calling the method EbicsClient.HVZ().
  • partnerid – The partner id of the corresponding order. Defaults to the partner id of the current user.
HVS(orderid, ordertype=None, hash=None, partnerid=None)

This method is part of the distributed signature and cancels a pending order.

Parameters:
  • orderid – The id of the order in question.
  • ordertype – The type of the order in question. If not specified, the corresponding order type is detected by calling the method EbicsClient.HVZ().
  • hash – The base64 encoded hash of the order to be canceled. If not specified, the corresponding hash is detected by calling the method EbicsClient.HVZ().
  • partnerid – The partner id of the corresponding order. Defaults to the partner id of the current user.
HVT(orderid, ordertype=None, source=False, limit=100, offset=0, partnerid=None, parsed=False)

This method is part of the distributed signature and downloads the transaction details of a pending order.

Parameters:
  • orderid – The id of the order in question.
  • ordertype – The type of the order in question. If not specified, the corresponding order type is detected by calling the method EbicsClient.HVU().
  • source – Boolean flag whether the original document of the order should be returned or just a summary of the corresponding transactions.
  • limit – Constrains the number of transactions returned. Only applicable if source evaluates to False.
  • offset – Specifies the offset of the first transaction to return. Only applicable if source evaluates to False.
  • partnerid – The partner id of the corresponding order. Defaults to the partner id of the current user.
  • parsed – Flag whether the received XML document should be parsed and returned as a structure of dictionaries or not.
Returns:

Either the raw XML document or a structure of dictionaries.

HVU(ordertypes=None, parsed=False)

This method is part of the distributed signature and downloads pending orders waiting to be signed.

Parameters:
  • ordertypes – An optional list of order types which are used to filter the result.
  • parsed – Flag whether the received XML document should be parsed and returned as a structure of dictionaries or not.
Returns:

Either the raw XML document or a structure of dictionaries.

HVZ(ordertypes=None, parsed=False)

This method is part of the distributed signature and downloads pending orders waiting to be signed. It acts like a combination of EbicsClient.HVU() and EbicsClient.HVD().

Parameters:
  • ordertypes – An optional list of order types which are used to filter the result.
  • parsed – Flag whether the received XML document should be parsed and returned as a structure of dictionaries or not.
Returns:

Either the raw XML document or a structure of dictionaries.

INI()

Sends the public key of the electronic signature. Returns the assigned order id.

PTK(start=None, end=None)

Downloads the customer usage report in text format.

Parameters:
  • start – The start date of requested processes. Can be a date object or an ISO8601 formatted string.
  • end – The end date of requested processes. Can be a date object or an ISO8601 formatted string.
Returns:

The customer usage report.

PUB(bitlength=2048, keyversion=None)

Creates a new electronic signature key, transfers it to the bank and updates the user key ring.

Parameters:
  • bitlength – The bit length of the generated key. The value must be between 1536 and 4096 (default is 2048).
  • keyversion – The key version of the electronic signature. Supported versions are A005 (based on RSASSA-PKCS1-v1_5) and A006 (based on RSASSA-PSS). If not specified, the version of the current signature key is used.
Returns:

The assigned order id.

SPR()

Locks the EBICS access of the current user.

STA(start=None, end=None, parsed=False)

Downloads the bank account statement in SWIFT format (MT940).

Parameters:
  • start – The start date of requested transactions. Can be a date object or an ISO8601 formatted string.
  • end – The end date of requested transactions. Can be a date object or an ISO8601 formatted string.
  • parsed – Flag whether the received MT940 message should be parsed and returned as a dictionary or not. See function fintech.swift.parse_mt940().
Returns:

Either the raw data of the MT940 SWIFT message or the parsed message as dictionary.

VMK(start=None, end=None, parsed=False)

Downloads the interim transaction report in SWIFT format (MT942).

Parameters:
  • start – The start date of requested transactions. Can be a date object or an ISO8601 formatted string.
  • end – The end date of requested transactions. Can be a date object or an ISO8601 formatted string.
  • parsed – Flag whether the received MT942 message should be parsed and returned as a dictionary or not. See function fintech.swift.parse_mt940().
Returns:

Either the raw data of the MT942 SWIFT message or the parsed message as dictionary.

bank

The EBICS bank (read-only).

check_ssl_certificates

Flag whether remote SSL certificates should be checked for validity or not. The default value is set to True.

confirm_download(trans_id=None, success=True)

Confirms the receipt of a previously executed download.

It is usually used to mark received data, so that it is not included in further downloads. Some banks require to confirm a download before new downloads can be performed.

Parameters:
  • trans_id – The transaction id of the download. If not specified, the transaction id of the last EBICS download is used (see last_trans_id).
  • success – Informs the EBICS server whether the downloaded data was successfully processed or not.
download(order_type, params=None)

Performs an arbitrary EBICS download request.

Parameters:
  • order_type – The id of the intended order type.
  • params – A list or dictionary of parameters which are added to the EBICS request.
Returns:

The downloaded data. The returned transaction id is stored in the attribute last_trans_id.

last_trans_id

This attribute stores the transaction id of the last download process (read-only).

timeout

The timeout in seconds for EBICS connections (default: 30).

upload(order_type, data, params=None)

Performs an arbitrary EBICS upload request.

Parameters:
  • order_type – The id of the intended order type.
  • data – The data to be uploaded.
  • params – A list or dictionary of parameters which are added to the EBICS request.
Returns:

The id of the uploaded order if applicable.

user

The EBICS user (read-only).

version

The EBICS protocol version (read-only).

fintech.ebics.EbicsClientCompat(keys, passphrase, url, hostid, partnerid, userid, systemid=None, keyversion='A006', version='H004')

Factory function to create an EbicsClient instance which is compatible with an EbicsClient instance from PyEBICS version 2 (depreciated). Do not use this function for further development!

Parameters:
  • keys – The path to a key file or a dictionary of keys. If the key file does not exist or the dictionary is empty, new keys (2048 bit) will be created.
  • passphrase – The passphrase by which all keys will be encrypted/decrypted.
  • url – The URL of the EBICS server.
  • hostid – The HostID of the bank.
  • partnerid – The assigned PartnerID (Kunden-ID).
  • userid – The assigned UserID (Teilnehmer-ID).
  • systemid – The assigned SystemID (usually unused).
  • keyversion – The key version of the electronic signature. Supported versions are A005 and A006 (default).
  • version – EBICS protocol version. At time the only supported version is 2.5 (H004).
exception fintech.ebics.EbicsVerificationError

The EBICS response could not be verified.

exception fintech.ebics.EbicsTechnicalError(code, message=None)

The EBICS server returned a technical error. The corresponding EBICS error code can be accessed via the attribute code.

exception fintech.ebics.EbicsFunctionalError(code, message=None)

The EBICS server returned a functional error. The corresponding EBICS error code can be accessed via the attribute code.

Examples

Initializing an EBICS account

from fintech.ebics import EbicsKeyRing, EbicsBank, EbicsUser, EbicsClient

keyring = EbicsKeyRing(keys='~/mykeys', passphrase='mysecret')
bank = EbicsBank(keyring=keyring, hostid='MYBANK', url='https://www.mybank.de/ebics')
user = EbicsUser(keyring=keyring, partnerid='CUSTOMER123', userid='USER1')
# Create new keys for this user
user.create_keys(keyversion='A006', bitlength=2048)

client = EbicsClient(bank, user)
# Send the public electronic signature key to the bank.
client.INI()
# Send the public authentication and encryption keys to the bank.
client.HIA()

# Create an INI-letter which must be printed and sent to the bank.
user.create_ini_letter(bankname='MyBank AG', path='~/ini_letter.pdf')

# After the account has been activated the public bank keys
# must be downloaded and checked for consistency.
print client.HPB()

# Finally the bank keys must be activated.
bank.activate_keys()

Download Bank to Customer Statements (camt.53)

from fintech.ebics import EbicsKeyRing, EbicsBank, EbicsUser, EbicsClient

keyring = EbicsKeyRing(keys='~/mykeys', passphrase='mysecret')
bank = EbicsBank(keyring=keyring, hostid='MYBANK', url='https://www.mybank.de/ebics')
user = EbicsUser(keyring=keyring, partnerid='CUSTOMER123', userid='USER1')
client = EbicsClient(bank, user)

# Download camt.53 documents
docs = client.C53('2014-02-01', '2014-02-07')
# Print all received documents
for name, xml in docs.items():
    print xml
# Print the transaction id for this download process
print client.last_trans_id

Kann ich
  Ihnen helfen?


Schreiben Sie mir
doch einfach unter
giraffe@joonis.de