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