joonis Logo

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, first, last).

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]

There are several options available to start the server:

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

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 (SHA1) of the password.
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.
License:

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:

[Main]
Bind Address = localhost
Port = 8830
Threaded = true
Log File = /path/to/rpc.log
Log Level = info
Auth User = user1:e38ad214943daad1d64c102faec29de4afe9da3d
            user2:2aa60a8ff7fcd473d321e0146afd9e26df395147
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]
User = user1:e38ad214943daad1d64c102faec29de4afe9da3d
       user2:2aa60a8ff7fcd473d321e0146afd9e26df395147

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

Download

At time the XML-RPC server is not included in the main FinTech package. So you have to download and install the script by hand. Released under the GNU/GPL.

fintech-rpc.py (v0.3.1)

Examples

To be written ...

Changelog

v0.3.1 [2015-04-22]
  • Now Amount objects are converted to dictionaries
v0.3.0 [2015-04-14]
  • Added Python 2/3 compatibility
v0.2.0 [2015-01-26]
  • Adjusted some imports to be conform with the new package name
  • Renamed the script from ebics-rpc.py to fintech-rpc.py
v0.1.3 [2014-10-10]
  • Fixed a bug converting datetime arguments
v0.1.2
  • First public release

Can I
  help you?


Just drop me a line at
giraffe@joonis.de