commit 6978fed0ddf1bfa2d658a3b17a309b34e6357944
parent 9bbc32c0484be670f4a32cc3e9e4a0faae994851
Author: Antoine A <>
Date: Thu, 22 Feb 2024 17:49:26 +0100
Improve regional currency manual
Diffstat:
2 files changed, 76 insertions(+), 14 deletions(-)
diff --git a/frags/regional-manual-use.rst b/frags/regional-manual-use.rst
@@ -37,7 +37,7 @@ This section describes the interaction between the Taler graphical wallet (Andro
iOS, WebExtensions) and the regional currency system.
You need to add your regional currency exchange to the wallet. This can
-be done by scanning a QR code with a ``taler://withdraw-exchange/exchange.$DOMAIN``
+be done by scanning a QR code with a ``taler://withdraw-exchange/exchange.$DOMAIN/$MASTER_PUB``
URL or by manually entering the URL into the respective ``Add exchange``
dialogue.
diff --git a/libeufin/regional-automated-manual.rst b/libeufin/regional-automated-manual.rst
@@ -147,7 +147,79 @@ Connecting to a Fiat Bank: the EBICS setup
To complete the conversion setup, you have to set up an EBICS subscriber using a fiat bank account at a bank dealing in fiat currency that offers an online banking protocol supported by LibEuFin Nexus.
-.. include:: ../frags/nexus-ebics-setup.rst
+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/libeufin-nexus.conf`` configuration file.
+
+.. note::
+ As legacy transactions in that bank account would likely confuse the system, it is advisable to use a fresh bank account with an empty transaction history.
+
+The following snippet shows the mandatory configuration values:
+
+.. _core-config:
+
+.. code-block:: ini
+
+ [nexus-ebics]
+ # 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
+
+ # Account information
+ IBAN = CH7789144474425692816
+ BIC = POFICHBEXXX
+ NAME = John Smith S.A.
+
+.. warning::
+ This combination of HOST_ID, USER_ID and PARTNER_ID must never be used by another instance of libeufin-nexus 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 ``/var/lib/libeufin-nexus/client-ebics-keys.json``.
+
+Make sure this file is accessible to the user running ``libeufin-nexus``, for the default services you should run:
+
+.. code-block:: console
+
+ $ chown libeufin-nexus:libeufin-nexus /var/lib/libeufin-nexus/client-ebics-keys.json
+
+Create new client keys
+^^^^^^^^^^^^^^^^^^^^^^
+
+Run the following command to start the EBICS setup process:
+
+.. code-block:: console
+
+ $ sudo -u libeufin-nexus libeufin-nexus ebics-setup
+
+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-nexus-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
+
+ $ sudo -u libeufin-nexus libeufin-nexus ebics-setup
+
+The EBICS setup is finished once the bank keys have been accepted.
+
Configuring the Exchange for Conversion
+++++++++++++++++++++++++++++++++++++++
@@ -170,22 +242,12 @@ the possibility of currency conversion (cash in):
.. code-block:: console
- # taler-exchange-offline \
+ $ sudo -u taler-exchange-offline taler-exchange-offline \
enable-account \
payto://iban/$IBAN?receiver-name=$NAME \
- conversion-url "$CONVERSION_URL" \
+ conversion-url "${PROTO}://bank.$DOMAIN/conversion-info/" \
upload
-Here, the ``$CONVERSION_URL`` must be set to the base URL of the conversion
-endpoint of the bank, which should be ``https://bank.$DOMAIN/conversion-info/``
-in our setup.
-
-.. note::
-
- The above command adds a **second** bank account to the exchange.
- You (or the guided setup script) should have already enabled the
- regional currency bank account (without any "conversion-url").
-
System ON!
++++++++++
