commit cdae8589d848340d7c6facc108102c1aae8e7af4
parent ce1b29ad0798c70421b19eaf94b2884a9dba518e
Author: Antoine A <>
Date: Tue, 4 Feb 2025 16:22:52 +0100
libeufin-nexus: add dialect doc and update manual
Diffstat:
3 files changed, 115 insertions(+), 9 deletions(-)
diff --git a/libeufin/index.rst b/libeufin/index.rst
@@ -28,6 +28,7 @@ LibEuFin is a project providing free software tooling for European FinTech.
:glob:
nexus-manual
+ nexus-dialects
bank-manual
regional-automated-manual
regional-custom-manual
diff --git a/libeufin/nexus-dialects.rst b/libeufin/nexus-dialects.rst
@@ -0,0 +1,94 @@
+..
+ 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
+
+Nexus bank dialects
+###################
+
+LibEuFin Nexus is an EBICS facilitator. It offers a command line interface to
+setup EBICS access, download banking records, and submit payments. LibEuFin Nexus is not a generic EBICS client but a Taler specific one.
+
+Today, the LibEuFin implementation supports EBICS 3.0 and has been
+tested with Postfinance (CHF), GLS (EUR) and Maerki Baumann (CHF). Please note
+that banks tend to have their own dialects of finance messages and thus other
+retail banks may or may not work. Contact us if you need support for another
+bank or core banking protocol.
+
+We use different parsing logic depending of the bank dialect. This difference are documented in this file.
+
+In ISO 20022 specifications, most fields are optional and the same information
+can be written several times in different places. For LibEuFin, we're only
+interested in a subset of the available values that can be found in both camt.
+052, camt.053 and camt.054. We only parse payment transactions (transaction domain code PMNT) and ignore all others. This mean we ignore some debits that could originate from you banks for fees or taxes.
+
+As the ISO20022 standard does not provide a perfect transaction identifier, we
+will use either the ``UETR`` (unique end-to-end transaction reference), which
+is a universal identifier, or the ``TxId`` (TransactionIdentification),
+assigned by the first instructing agent.
+While these two identifiers are optional in the standard, they are mandatory in
+local standards, and have the advantage of being unique and can be used to
+track a transaction between banks.
+
+.. contents:: Table of Contents
+ :local:
+
+
+postfinance
+===========
+
+camt
+----
+
+We use ``UETR`` as the transaction ID.
+We parse reversal from camt.053 but do not parse other transactions as the wire transfer subject is missing. We parse incoming and outgoing transactions from camt.054 where the wire transfer subject is present.
+
+pain.001
+--------
+
+We use the pain.001.001.09.ch.03 schema with the default service level. Transactions will only work between Swiss accounts.
+
+gls
+===
+
+camt
+----
+
+We use ``TxId`` as the transaction ID.
+We parse incoming instant transactions from camt.054 and We parse incoming and outgoing transactions as well as reversals from both camt.052 and camt.053.
+
+pain.001
+--------
+
+We use the pain.001.001.09 schema with the SEPA service level. Transactions will work with any other SEPA account.
+
+maerki_baumann
+==============
+
+As Maerki Baumann does no provide an EBICS API you will have to use the manual import and export commands.
+
+camt
+----
+
+We use ``UETR`` as a transaction identifier.
+Credit fees are parsed.
+We parse incoming and outgoing transactions as well as reversals from camt.053.
+
+pain.001
+--------
+
+We use the pain.001.001.09.ch.03 schema with the default service level. Transactions will only work between Swiss accounts.
+\ No newline at end of file
diff --git a/libeufin/nexus-manual.rst b/libeufin/nexus-manual.rst
@@ -1,6 +1,6 @@
..
This file is part of GNU TALER.
- Copyright (C) 2014-2024 Taler Systems SA
+ Copyright (C) 2014-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
@@ -13,6 +13,7 @@
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
@author Florian Dold
@author Marcello Stanisci
@author Christian Grothoff
@@ -24,15 +25,14 @@
Nexus Manual
############
-LibEuFin Nexus is an EBICS facilitator. It offers a command line interface to
-setup EBICS access, download banking records, and submit payments. Today, the
-LibEuFin implementation supports EBICS 2.5 and 3.0 and has been tested with
-the Postfinance (CHF). Please note that banks tend to have their own dialects
-of finance messages and thus other retail banks may or may not work. Contact
-us if you need support for another bank or core banking protocol.
+LibEuFin Nexus is an EBICS facilitator. It offers a command line interface to
+setup EBICS access, download banking records, and submit payments. LibEuFin Nexus is not a generic EBICS client but a Taler specific one.
-Future versions will offer a Web API to allow Taler exchanges to talk to their
-banks.
+Today, the LibEuFin implementation supports EBICS 3.0 and has been
+tested with Postfinance (CHF), GLS (EUR) and Maerki Baumann (CHF). Please note
+that banks tend to have their own dialects of finance messages and thus other
+retail banks may or may not work. Contact us if you need support for another
+bank or core banking protocol.
In this manual, we explain how to setup an EBICS subscriber. We assume that
the bank has already granted EBICS access to the subscriber.
@@ -294,6 +294,16 @@ the present:
Use the ``IGNORE_BOUNCES_BEFORE`` configuration to prevent malformed transactions from being bounced a second time when they are registered again.
+Manual balance adjustement
+==========================
+
+As LibEuFin Nexus is a Taler-specific EBICS client, it ignores non-payment
+transactions. This means that certain debits from your banks for fees or taxes
+can be ignored. This imply that the actual balance of your bank account may deviate from that expected by Taler Exchange, leading to Exchange bankruptcy.
+
+To fix this, you must periodically send administrative balance adjustment
+transfers conaining "ADMIN BALANCE ADJUST" in their subject.
+
Manual EBICS import & export
============================
