commit c31719e2c873ed9f3a529ead33a83a9f75f583bb
parent 9fe0b8090dd8287a0715af40b1f689efd5bc5ff8
Author: Antoine A <>
Date: Mon, 11 Nov 2024 19:33:27 +0100
libeufin: update manual and man pages
Diffstat:
4 files changed, 41 insertions(+), 5 deletions(-)
diff --git a/libeufin/nexus-manual.rst b/libeufin/nexus-manual.rst
@@ -214,10 +214,30 @@ Downloading payments must follow a successful `EBICS subscriber setup
subscriber accepted the bank keys. Furthermore, the database has to
be set up.
-The responsible subcommand for sending payments is ``ebics-fetch``, and its
-configuration is a **superset** of core-config_. On top of that, it expects
-the database connection string and *optionally* a frequency at which it will
-downloads any new EBICS files and register them in the database.
+The responsible subcommand for fetching and registering payments is
+``ebics-fetch``, and its configuration is a **superset** of core-config_. On
+top of that, it expects the database connection string and *optionally* a
+frequency and a checkpoint time of day.
+
+For the best user experience, new transactions should be registered as soon as
+they are booked. This is especially important for instant transactions, which
+reach final status in ~10 seconds. On the other hand, EBICS document fetches
+are slow and expensive and should not be performed more than necessary.
+
+``ebics-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-nexus``, they can consume documents before they are ingested. In case of bank downtime, the status of
+documents can be lost. This is why ``ebics-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
@@ -228,6 +248,13 @@ The frequency **may** be specified as
The supported time units are ``s`` (seconds), ``m`` (minutes), ``h`` (hours).
+The checkpoint time of day **may** be specified as
+
+.. code-block:: ini
+
+ [nexus-fetch]
+ CHECKPOINT_TIME_OF_DAY = 19:00
+
Assuming that ``$CONFIG_FILE`` contains all required options, the following
command would download any unseen EBICS files:
diff --git a/manpages/libeufin-bank.1.rst b/manpages/libeufin-bank.1.rst
@@ -99,6 +99,8 @@ Its options are as follows:
Optional token description.
**--refreshable**
Make the token refreshable into a new token.
+**--current-token** *TOKEN*
+ Current token to reuse if still valid.
**-h** \| **--help**
Print short help on options.
diff --git a/manpages/libeufin-nexus.1.rst b/manpages/libeufin-nexus.1.rst
@@ -115,7 +115,7 @@ This subcommand fetches EBICS files from the bank. Incoming payments are recorde
If ACCOUNT_TYPE is ``exchange``, incoming payments with an invalid Taler subject are bounced. Bounces are submitted by ebics-submit.
-Fetches are executed at 'FREQUENCY' or any time a real-time EBICS notification is received.
+Fetches of new documents are executed at 'FREQUENCY' or any time a real-time EBICS notification is received. Every day, a checkpoint is performed, during which all documents since the last checkpoint are fetched.
**-c** \| **--config** *config_file*
Specifies the configuration file.
@@ -125,6 +125,10 @@ Fetches are executed at 'FREQUENCY' or any time a real-time EBICS notification i
Execute once and return, ignoring the 'FREQUENCY' configuration value.
**--pinned-start** *YYYY-MM-DD*
Only supported in --transient mode, this option lets specify the earliest timestamp of the downloaded documents.
+**--peek**
+ Only supported in --transient mode, do not consume fetched documents.
+**--checkpoint**
+ Only supported in --transient mode, run a checkpoint.
**--debug-ebics** *log_dir*
Log EBICS transactions steps and payload at log_dir.
**-h** \| **--help**
diff --git a/manpages/libeufin-nexus.conf.5.rst b/manpages/libeufin-nexus.conf.5.rst
@@ -90,6 +90,9 @@ FREQUENCY
Duration value to instruct the ``ebics-fetch`` subcommand how often it should
download from the bank.
+CHECKPOINT_TIME_OF_DAY
+ At what time HH:MM of day should ``ebics-fetch`` perform a checkpoint.
+
IGNORE_TRANSACTIONS_BEFORE
Ignore all transactions before a certain YYYY-MM-DD date, useful when you want to use an existing account with old transactions that should not be bounced.
