English Deutsch

FinTech Open Banking RPC Server

The FinTech XML-RPC-Server enables third-party programming languages like PHP, Ruby, Java or Perl to make use of the functionality of the Python FinTech library. It provides a global Open Banking API which is mapped to the internal structure of PyFintech.

How it works

First of all the FinTech XML-RPC service is meant to be used only within a LAN for security reasons. Do not use it over the internet.

All you need is an XML-RPC client in your favourite programming language. Make sure that it supports the RPC null/nil type.

An XML-RPC request consists of a method name (hereafter called RPC method) and an arbitrary number of unlabeled positional parameters (hereafter called RPC parameter). That is how an XML-RPC service generally works.

Each RPC method is mapped onto the functions and classes of the different FinTech modules. For example the RPC method iban.create_iban calls the function create_iban of the module iban. The RPC method ebics.EbicsClient.C53 creates an instance of the class EbicsClient from the ebics module and then calls its method C53.

The passed RPC parameters are assigned to the functions and/or classes that were addressed by the RPC method. If an RPC parameter is a structure, its values are passed to the function or class based on the corresponding key names. If it is an array, its values are passed in the respective order. Any other data type will be passed as a single argument. For example the RPC method iban.create_iban requires exactly one RPC parameter (a structure or an array with the expected parameters). The RPC method ebics.EbicsClient.C53 requires one or two RPC parameters. The first one is passed to the EbicsClient class as described above to create an instance, the second one is then passed to the method C53 of the just created EbicsClient instance.

For the most part you can refer to the standard FinTech documentation with one exception: Whenever an Account instance is expected you can alternatively pass a simple structure which represents an account. Such a structure can be filled with any parameter the Account instantiation method expects (iban, name, country, city, postcode, street). In addition a value can be set for the keys ultimate_name, creditor_id and mandate. The latter must be again a structure of arguments that can be passed to the method set_mandate of an Account instance (mref, signed, recurrent).

Return values are converted to the corresponding data types of the XML-RPC protocol. However if the return value is an object that cannot be represented by an XML-RPC data type (like the instance of a class), the object will be cached and a unique object identifier is returned. With this object id it is then possible to access the methods of the cached object and also to use it as an argument for other RPC calls.

Each session has its own object cache. A session is always based on the username set by the HTTP Basic Authorization header. It can be a fictional name if HTTP Basic Authorization was not activated on the server-side (see option --auth-user below). If there is no HTTP Basic Authorization header available, a global session is used.

There are some additional RPC methods that do not belong to the FinTech library itself:

  • echo
    Returns a copy of the passed RPC parameters for testing purposes.
  • version
    Returns the current version of the used FinTech library.
  • has_object
    Checks whether the passed string is a valid object id for an actual object within the current session or not.
  • purge
    Removes objects from the object cache of the current session. The optional RPC parameter must be either a string with an object id or an array of object ids to be removed. If it is omitted, all existing objects are removed. This method should be called at least once at the end of each procedure to clear the object cache. It returns the number of removed objects.

The XML-RPC server also supports multicall requests. This is useful if you want to call an RPC method repeatedly. For example if you want to add a large number of transactions to a SEPA document, you can use this to combine all calls to add_transaction into one single request.

Starting the server

To start the server just run the fintech-rpc command.

usage: fintech-rpc [-h] [-c FILE] [-b ADDRESS] [-p PORT] [-t] [-f FILE] [-l LEVEL] [-a USER:HASH]
                   [-i ADDRESS] [-K FILE] [-C FILE] [-n NAME] [-k KEYCODE] [-u USERID]
                   [{install,uninstall,start,stop,restart,status}]

Fintech RPC server

positional arguments:
  {install,uninstall,start,stop,restart,status}
                        optional service commands

optional arguments:
  -h, --help            show this help message and exit
  -c FILE, --config-file FILE
                        load specified configuration file
  -b ADDRESS, --bind-address ADDRESS
                        bind server to given address (default: localhost)
  -p PORT, --port PORT  the port number to use (default: 8830)
  -t, --threaded        create a threaded server
  -e FILE, --ext-file FILE
                        load RPC extension class from specified file
  -f FILE, --log-file FILE
                        write log to specified file
  -l LEVEL, --log-level LEVEL
                        log level (debug, info, warning, error, critical)

authorization:
  user management options

  -a USER:HASH, --auth-user USER:HASH
                        enable http basic auth and add the specified user
                        HASH must be set to the hash (SHA256) of the password.
  -i ADDRESS, --auth-address ADDRESS
                        allow access only from the specified ip address

secure socket layer:
  options to enable SSL

  -K FILE, --ssl-key FILE
                        path to ssl key file
  -C FILE, --ssl-cert FILE
                        path to ssl cert file

license:
  options to register a licensed version

  -n NAME, --license-name NAME
                        name of licensee
  -k KEYCODE, --license-key KEYCODE
                        license key code
  -u USERID, --license-user USERID
                        EBICS user id (must be applied for each user id)
Configuration files

All options can be set by loading a specified configuration file based on the INI file format. Each property is mapped to its corresponding long option name listed above, whereas hyphens can be replaced with blanks. The main section is named [Main]. For reasons of clarity properties can be grouped into other sections by splitting off one or more words from the beginning of the option name and using this part as the section name and the remaining part as the property name. Therefore the following two examples have the same meaning:

[Main]
Bind Address = localhost
Port = 8830
Threaded = true
Log File = /path/to/rpc.log
Log Level = info
Auth Address = 192.168.0.121
               192.168.0.122
Auth User = user1:9497741b24eb36fff68dfc79a46fc9d3927f9813670c4a4636113d9b64b79a44
            user2:f7dfc6aab1793f8fcd7e208bcdca48fdeef0a5cf70643e0593ac3b9e3d0cbe25
License Name = Company
License Key = MY-KEY-CODE
License User = MYUSERID
[Main]
Bind Address = localhost
Port = 8830
Threaded = true

[Log]
File = /path/to/rpc.log
Level = info

[Auth]
Address = 192.168.0.121
          192.168.0.122
User = user1:9497741b24eb36fff68dfc79a46fc9d3927f9813670c4a4636113d9b64b79a44
       user2:f7dfc6aab1793f8fcd7e208bcdca48fdeef0a5cf70643e0593ac3b9e3d0cbe25

[License]
Name = Company
Key = MY-KEY-CODE
User = MYUSERID

If an option supports a list of values, you can accomplish this by adding each extra value on a separate line which must begin with at least one whitespace character (see option Auth User in the example above).

Installing as service

The RPC server can be installed as a system service on Linux (systemd), macOS (launchd) and Windows (requires pywin32 package, see below):

fintech-rpc install

You get asked if the service should run as a specified user and whether the service should be started automatically on reboot or not. All applied command line arguments will be observed. Best practice is to create a configuration file and pass it to the install command:

fintech-rpc install -c /path/to/config.ini

Now you are able to start and stop the service or check its status:

fintech-rpc start
fintech-rpc stop
fintech-rpc status

To uninstall the service, just do it:

fintech-rpc uninstall
Requirements for Windows

Windows requires the pywin32 package before you can install the service. You must run all commands from an elevated ("Run as Administrator") command prompt.

pip install pywin32

Finally run the pywin32 postinstall script (adjust the path to your Python installation):

python "C:\Program Files\Python38\Scripts\pywin32_postinstall.py" -install
Share it Facebook Twitter Email AddThis