[taler-docs] branch master updated (649795e3 -> cdae8589)

[Admin]

This is an automated email from the git hooks/post-receive script.

antoine pushed a change to branch master
in repository taler-docs.

    from 649795e3 [common,exchange] -typo fixes
     new ce1b29ad magnet-bank: update manpages
     new cdae8589 libeufin-nexus: add dialect doc and update manual

The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.


Summary of changes:
 libeufin/index.rst                    |  1 +
 libeufin/nexus-dialects.rst           | 94 +++++++++++++++++++++++++++++++++++
 libeufin/nexus-manual.rst             | 28 +++++++----
 manpages/taler-magnet-bank.conf.5.rst |  4 +-
 4 files changed, 116 insertions(+), 11 deletions(-)
 create mode 100644 libeufin/nexus-dialects.rst

diff --git a/libeufin/index.rst b/libeufin/index.rst
index 4fd7668c..42269040 100644
--- 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
new file mode 100644
index 00000000..21cc97e8
--- /dev/null
+++ 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
index b29410ea..a796da79 100644
--- 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
 ============================
 
diff --git a/manpages/taler-magnet-bank.conf.5.rst 
b/manpages/taler-magnet-bank.conf.5.rst
index 89753442..993fa9d1 100644
--- a/manpages/taler-magnet-bank.conf.5.rst
+++ b/manpages/taler-magnet-bank.conf.5.rst
@@ -39,10 +39,10 @@ CONSUMER_SECRET
   Your Magnet Bank API confidential key.
 
 IBAN
-  IBAN of the bank account that is associated with the EBICS subscriber.
+  IBAN of the Magnet Bank account to sync.
 
 NAME
-  Legal entity that is associated with the EBICS subscriber.
+  Legal entity that is associated with the Magnet Bank account.
 
 KEYS_FILE
   Filesystem location where taler-magnet-bank should store the crypto keys.

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.