English Deutsch

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

fintech-rpc [options]

  -h, --help            Shows a help message and exits.
  -c FILE, --config-file=FILE
                        Loads the specified configuration file (see below).
  -b ADDRESS, --bind-address=ADDRESS
                        Binds the server to the given address (default: localhost)
  -p PORT, --port=PORT  The port number to listen on (default: 8830)
  -t, --threaded        Creates a threaded server.
  -f FILE, --log-file=FILE
                        Writes log messages to the specified file instead to stdout.
  -l LEVEL, --log-level=LEVEL
                        The log level to use. One of debug, info, warning, error or critical.

    User management options

    -a USER:HASH, --auth-user=USER:HASH
                        Enables HTTP Basic Authorization and adds 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
                        The path to the SSL key file.
    -C FILE, --ssl-cert=FILE
                        The path to the SSL certificate file.

    Options to register a licensed version

    -n NAME, --license-name=NAME
                        The name of the licensee.
    -k KEYCODE, --license-key=KEYCODE
                        The license key code.
    -u USERID, --license-user=USERID
                        The EBICS user id (must be applied for each EBICS 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:

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

File = /path/to/rpc.log
Level = info

Address =

User = user1:9497741b24eb36fff68dfc79a46fc9d3927f9813670c4a4636113d9b64b79a44

Name = Company

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