commit 847bd00b76a035153c840a95aa2ad56704db4114
parent 937228cd754ed2ee69f5a0460e05389d55f0395f
Author: Antoine A <>
Date: Mon, 21 Jul 2025 11:50:56 +0200
nexus: improve dialect documentation
Diffstat:
1 file changed, 48 insertions(+), 45 deletions(-)
diff --git a/libeufin/nexus-dialects.rst b/libeufin/nexus-dialects.rst
@@ -29,66 +29,69 @@ 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:
+EBICS
+=====
+
+Protocol versions
+-----------------
-postfinance
-===========
+The following protocol versions are supported:
+- V2.5 H004
+- v3.0 H005
-camt
-----
+We use V3.0 for all file related operations and V2.5 for key management for *gls* dialect until GLS correctly support it. We plan to drop V2.5 support in 2026.
-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.
+Administrative Orders
+---------------------
-pain.001
---------
+We use the following EBICS orders: HEV, INI, HIA, HPB, HKD, HAA, BTU, BTD.
+HAA and HKD are optional orders but are required for LibEuFin Nexus to work.
-We use the pain.001.001.09.ch.03 schema with the default service level. Transactions will only work between Swiss accounts.
+ISO20022
+========
-gls
-===
+CAMT files
+----------
-camt
-----
+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.
-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.
+- postfinance
+ - BTD PSR CH pain.002 10 ZIP
+ - BTD STM CH camt.052 08 ZIP
+ - BTD EOP CH camt.053 08 ZIP
+ - BTD REP CH camt.054 08 ZIP
+- gls
+ - BTD REP DE pain.002 ZIP SCI
+ - BTD REP DE pain.002 ZIP SCT
+ - BTD STM DE camt.052 ZIP
+ - BTD EOP DE camt.053 ZIP
+ - BTD STM DE camt.054 ZIP
+ - BTD STM DE camt.054 ZIP SCI
-pain.001
---------
+If older versions of files are advertised as being present, we will also fetch them.
-We use the pain.001.001.09 schema with the SEPA service level. Transactions will work with any other SEPA account.
+As the ISO20022 standard does not provide a perfect transaction identifier we use a combinaison of the ``UETR`` (unique end-to-end transaction reference), which is a universal identifier, the ``TxId`` (TransactionIdentification), assigned by the first instructing agent and the ``AcctSvcrRef`` (AccountServicerReference) assigned by the account servicing institution.
+Those three identifiers are optional in the standard and sometimes mandatory in local standards. Combining the three we can track transactions across different files.
-maerki_baumann
-==============
+PAIN files
+----------
-As Maerki Baumann does no provide an EBICS API you will have to use the manual import and export commands.
+Direct debits will use the following orders
+- postfinance: BTU MCT CH pain.001 09
+- gls: BTU SCT pain.001
-camt
-----
+Instant direct debits will use the following orders
+- gls: BTU SCI DE pain.001
-We use ``UETR`` as a transaction identifier.
-Credit fees are parsed.
-We parse incoming and outgoing transactions as well as reversals from camt.053.
+Instant direct debits are always tried first if they are supported, and LibEuFin fall back on ordinary direct debits in case of failure. If you do not want LibEuFin to send instant direct debit you can disable the order for LibEuFin's specific subscriber at your bank.
-pain.001
---------
+The following pain.001 format are used:
-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
+- postfinance & maerki_baumann: pain.001.001.09.ch.03 with the default service level this will only work between swiss accounts
+- gls: pain.001.001.09 with the SEPA service level this works with any other SEPA account
+\ No newline at end of file
