commit 211f01b755e6877d12e8b1d8fef9482f69ad39a8
parent af322f1a958ad84756be4158994b10023cac1497
Author: Antoine A <>
Date: Fri, 5 Dec 2025 18:28:49 +0100
ebisync: add manual
Diffstat:
3 files changed, 253 insertions(+), 1 deletion(-)
diff --git a/frags/nexus-ebics-setup.rst b/frags/nexus-ebics-setup.rst
@@ -64,7 +64,7 @@ activate your account.
To that end, the previous run should have left a PDF document that you can
print, sign and send to the bank. Look for the message that looks like ``PDF
-file with keys created at '/tmp/libeufin-nexus-keys-$TIMESTAMP.pdf'``.
+file with keys created at '/tmp/libeufin-ebics-keys-$TIMESTAMP.pdf'``.
Once the bank has received and processed this document you can continue.
diff --git a/libeufin/ebisync-manual.rst b/libeufin/ebisync-manual.rst
@@ -0,0 +1,250 @@
+..
+ This file is part of GNU TALER.
+ Copyright (C) 2025 Taler Systems SA
+
+ TALER is free software; you can redistribute it and/or modify it under the
+ terms of the GNU Affero General Public License as published by the Free Software
+ Foundation; either version 2.1, or (at your option) any later version.
+
+ TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License along with
+ TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+
+ @author Antoine d'Aligny
+
+.. target audience: operator, developer
+
+.. _libeufin-ebisync:
+
+EbiSync Manual
+##############
+
+LibEuFin EbiSync is an EBICS synchronization tool. It offers a command line interface to setup EBICS access and download & submit ISO20022 files.
+
+Today, the LibEuFin implementation supports EBICS 3.0 and has been
+tested with Postfinance (CHF), GLS (EUR), Maerki Baumann (CHF) and Valiant (CHF). Contact us if you need support for another bank.
+
+In this manual, we explain how to setup an EBICS subscriber. We assume that
+the bank has already granted EBICS access to the subscriber.
+
+.. contents:: Table of Contents
+ :local:
+
+
+Installing EbiSync
+==================
+
+The following section was tested on an *OpenJDK 17* environment.
+
+
+Installing the libeufin-ebisync binary packages on Debian
+---------------------------------------------------------
+
+.. include:: ../frags/installing-debian.rst
+
+
+To install libeufin-ebisync, you can now simply run:
+
+.. code-block:: console
+
+ # apt install libeufin-ebisync
+
+Installing the libeufin-ebisync binary packages on Ubuntu
+---------------------------------------------------------
+
+.. include:: ../frags/installing-ubuntu.rst
+
+To install libeufin-ebisync, you can now simply run:
+
+.. code-block:: console
+
+ # apt install libeufin-ebisync
+
+
+Building from source
+--------------------
+
+Ebisync belongs to the LibEuFin project, and can be downloaded via Git:
+
+.. code-block:: console
+
+ $ git clone git://git.taler.net/libeufin
+
+Note that Kotlin and Gradle should already work on the host system.
+
+Navigate into the *libeufin* local repository, and from top-level run:
+
+.. code-block:: console
+
+ $ ./bootstrap
+ $ ./configure --prefix=$PREFIX
+ $ make install
+
+If the previous steps succeeded, the ``libeufin-ebisync`` command should
+be found in the $PATH.
+
+.. _ebisync-setup:
+
+Database setup
+==============
+
+The configuration file must include a connection string that
+tells EbiSync how it should connect to the database. The default
+is:
+
+.. code-block:: ini
+
+ [ebisyncdb-postgres]
+ config = postgres:///libeufin-ebisync
+
+You must make sure that this database exists and is accessible to the user
+running EbiSync before continuing. Then, the EbiSync database schema must be
+created (or updated) to the current EbiSync version using the following command:
+
+.. code-block:: console
+
+ $ libeufin-ebisync dbinit -c "$CONFIG_FILE"
+
+where ``$CONFIG_FILE`` is again the path to a configuration that contains at
+least the above ``[ebisyncdb-postgres]`` section.
+
+Setting up the EBICS subscriber
+===============================
+
+When you sign up for an EBICS-enabled bank account, the bank will provide you
+with various credentials. Those must be provided in the
+``/etc/libeufin-ebisync/ebisync.conf`` configuration file.
+
+The following snippet shows the mandatory configuration values:
+
+.. _core-config:
+
+.. code-block:: ini
+
+ [ebisync]
+ # Bank
+ HOST_BASE_URL = https://ebics.postfinance.ch/ebics/ebics.aspx
+ BANK_DIALECT = postfinance
+
+ # EBICS IDs
+ HOST_ID = PFEBICS
+ USER_ID = PFC00563
+ PARTNER_ID = PFC00563
+
+.. note::
+ Refer to the manpage ``libeufin-ebisync.conf(5)``
+ for the full array of configuration values.
+
+.. warning::
+ This combination of HOST_ID, USER_ID and PARTNER_ID must never be used by another instance of libeufin-ebisync or by other EBICS clients, otherwise data will be lost.
+
+Reuse existing client keys
+--------------------------
+
+If you have client keys from a previous EBICS setup you can copy the JSON file to the configured path ``CLIENT_PRIVATE_KEYS_FILE`` (``/var/lib/libeufin-ebisync/client-ebics-keys.json`` with the default config).
+
+Make sure this file is accessible to the user running ``libeufin-ebisync``, for the default services you should run:
+
+.. code-block:: console
+
+ $ chown libeufin-ebisync:libeufin-ebisync /var/lib/libeufin-ebisync/client-ebics-keys.json
+
+Create new client keys
+----------------------
+
+Assuming that the configuration file exists at ``$CONFIG_FILE``, the following
+command should start the EBICS setup process:
+
+.. code-block:: console
+
+ $ libeufin-ebisync setup -c "$CONFIG_FILE"
+
+If the previous command failed when running EBICS INI with an error code of
+``EBICS_INVALID_USER_OR_USER_STATE``, you need to confirm your keys to your bank to
+activate your account.
+
+To that end, the previous run should have left a PDF document that you can
+print, sign and send to the bank. Look for the message that looks like ``PDF
+file with keys created at '/tmp/libeufin-ebics-keys/$TIMESTAMP.pdf'``.
+
+Once the bank has received and processed this document you can continue.
+
+Get bank keys
+-------------
+
+Assuming that the configuration file exists at ``$CONFIG_FILE``, the following
+command will finish the EBICS setup process:
+
+.. code-block:: console
+
+ $ libeufin-ebisync setup -c "$CONFIG_FILE"
+
+The EBICS setup is finished once the bank keys have been accepted.
+
+Make sure this bank keys are accessible to the user running ``libeufin-ebisync``, for the default services you should run:
+
+.. code-block:: console
+
+ $ chown libeufin-ebisync:libeufin-ebisync /var/lib/libeufin-ebisync/bank-ebics-keys.json
+
+Fetching files
+==============
+
+Downloading payments must follow a successful `EBICS subscriber setup
+<ebisync-setup>`_, where the bank obtained the subscriber keys, and the
+subscriber accepted the bank keys. Furthermore, the database has to
+be set up.
+
+The responsible subcommand for fetching and registering payments is
+``fetch``, and its configuration is a **superset** of core-config_. On
+top of that, it expects the database connection string, the destination config and *optionally* a
+frequency and a checkpoint time of day.
+
+``fetch`` will run a periodical fetch of pending documents (documents
+that have never been fetched before). If the bank server supports it, it will
+also listen to real-time document availability notifications and fetch
+documents as soon as they are announced. This enables instant registration of
+instant transactions. If your bank server does not support real-time
+notifications, it is recommended that you fetch more often; otherwise, you can
+reduce the fetch frequency.
+
+Only fetching pending documents is not always reliable, if other EBICS clients
+use the same connection settings as ``libeufin-ebisync``, they can consume documents before they are ingested. In case of bank downtime, the status of
+documents can be lost. This is why ``fetch`` will run a checkpoint every
+day to download all documents generated since the last checkpoint.
+
+If the bank supports real-time notifications, you can expect transactions to be registered as soon as they are booked: ~10s for instant transactions and 24 to 72h for other transactions. Otherwise, expect a latency corresponding to the fetch frequency for instant transactions. Thanks to checkpointing, latency should not exceed one day.
+
+The frequency **may** be specified as
+
+.. code-block:: ini
+
+ [ebisync-fetch]
+ FREQUENCY = 5m
+
+The supported time units are ``s`` (seconds), ``m`` (minutes), ``h`` (hours).
+
+The checkpoint time of day **may** be specified as
+
+.. code-block:: ini
+
+ [ebisync-fetch]
+ CHECKPOINT_TIME_OF_DAY = 19:00
+
+Assuming that ``$CONFIG_FILE`` contains all required options, the following
+command would download any unseen EBICS files:
+
+.. code-block:: console
+
+ $ libeufin-ebisync fetch -c "$CONFIG_FILE" --transient
+
+The ``fetch`` subcommand will always cause libeufin-ebisync to download EBICS files and upload them to the configured destination.
+
+The ``--transient`` flag makes the command sync only
+once and return immediately afterwards. Without the flag, EbiSync
+will download at the frequency specified in the configuration or when it receive real time notifications.
+
+The ``--debug-ebics $SAVEDIR`` flag will cause EBICS transactions steps and payloads to be stored in ``$SAVEDIR/$YYYY-MM-DD`` where ``$YYYY-MM-DD`` represents the date when the download took place. This is mostly useful for debugging.
+\ No newline at end of file
diff --git a/libeufin/index.rst b/libeufin/index.rst
@@ -34,3 +34,4 @@ LibEuFin is a project providing free software tooling for European FinTech.
regional-custom-manual
regional-manual-use
setup-ebics-at-postfinance
+ ebisync-manual
