diff options
Diffstat (limited to 'libeufin/regional-custom-manual.rst')
| -rw-r--r-- | libeufin/regional-custom-manual.rst | 164 |
1 files changed, 164 insertions, 0 deletions
diff --git a/libeufin/regional-custom-manual.rst b/libeufin/regional-custom-manual.rst new file mode 100644 index 00000000..8477c18d --- /dev/null +++ b/libeufin/regional-custom-manual.rst @@ -0,0 +1,164 @@ +.. + This file is part of GNU TALER. + Copyright (C) 2014-2024 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 Florian Dold + @author Marcello Stanisci + @author Christian Grothoff + + +.. target audience: operator + +Regional Currency Custom Setup Manual +##################################### + +This manual describes how to setup a regional currency manually. If you want a guided setup you can follow the :doc:`automated setup manual<regional-automated-manual>`. + +.. contents:: Table of Contents + :local: + +.. include:: ../frags/regional-manual-architecture.rst + +Custom Manual Setup +=================== + +You first need to setup the :ref:`libeufin-bank<libeufin-bank>` and integrate it with a Taler exchange. + +If you don't want your regional currency to be backed by a fiat currency, you can stop here. + +Enabling Currency Conversion +++++++++++++++++++++++++++++ + +You need to setup the :ref:`libeufin-nexus<libeufin-nexus>` using a bank account at a bank dealing in fiat currency that +offers an online banking protocol supported by LibEuFin Nexus. + +Next, you have to enable conversion and should ensure that at least one TAN +channel for :ref:`multi-factor authentication <libeufin-mfa>` is configured. + +The following snippet shows how to enable conversion in ``libeufin-bank`` configuration: + +.. code-block:: ini + + [libeufin-bank] + ALLOW_CONVERSION = YES + FIAT_CURRENCY = EUR + +Make sure to (re)start the libeufin-bank after changing +these configuration options: + +.. code-block:: console + + # systemctl restart libeufin-bank + + +Web-based Configuration ++++++++++++++++++++++++ + +Now you have to set the conversion rates and the ``admin`` debt limit via the bank's web interface as the ``admin`` user. + +.. _regional-conversion-setup: + +Configuring the Exchange for Conversion ++++++++++++++++++++++++++++++++++++++++ + +This section explains how to enable currency conversion at the exchange, +which is critical for wallets to know how to wire fiat currency to an +exchange to obtain regional currency. + +You will need to use the ``taler-exchange-offline`` tool to inform the +exchange about the **fiat** bank account that can be used for cash in +operations and also specify the URL for currency conversion. Additionally, +you may also configure restrictions on the bank accounts that may originate +the funds, for example, to prevent international wire transfers that may expose +you to additional compliance risks. + +Given the ``$IBAN`` of the fiat currency bank account and ``$NAME`` as +the (URL-encoded) name of the exchange-account owner, the following +``taler-exchange-offline`` invocation can be used to notify wallets about +the possibility of currency conversion (cash in): + +.. code-block:: console + + # taler-exchange-offline \ + enable-account \ + payto://iban/$IBAN?receiver-name=$NAME \ + conversion-url "$CONVERSION_URL" \ + debit-restriction \ + deny \ + credit-restriction \ + regex \ + 'payto://iban/.*/CH.*?receiver-name=.*' \ + 'Swiss only' \ + '{ "de" : "nur Schweiz", \ + "fr" : "Suisse uniquement" }' + 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 that you can +leave out the "credit-restriction" if you want to allow international inbound +wire transfers. The "debit-restriction" is largely mandatory as in this setup +the taler-exchange-transfer is only configured to deal with the regional +currency bank. Crediting fiat bank accounts must thus be done via the +cash-out functionality of the regional currency bank account. + +.. 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! +++++++++++ + +The last step is to enable libeufin-nexus to :ref:`import incoming bank +transactions <receive-transaction-data>` (cash in) and to :ref:`trigger +outgoing bank transactions <sending-payments>` (cash out). + +.. code-block:: console + + # systemctl enable --now libeufin-nexus.target + + +Configuring exchange terms +++++++++++++++++++++++++++ + +You can use your own terms of service and privacy policy. You can use the default templates in ``/usr/share/taler/terms`` as a guide. +Assuming you have custom terms of service and privacy policy ``rst`` teamplte files at ``TOS_PATH`` and ``PRIVACY_PATH``, the following commands generate the terms files: + +.. code-block:: console + + # taler-terms-generator -i "$TOS_PATH" + # taler-terms-generator -i "$PRIVACY_PATH" + +You now have to specify the terms file names in the exchange config: + +.. code-block:: console + + # TERMS_ETAG="$(basename "$TOS_PATH" .rst)" + # PRIVACY_ETAG="$(basename "$PRIVACY_PATH" .rst)" + +.. code-block:: ini + + [exchange] + TERMS_ETAG=${TERMS_ETAG} + PRIVACY_ETAG=${PRIVACY_ETAG} + +Make sure to restart taler-exchange after changing these configuration options: + +.. code-block:: console + + # systemctl restart taler-exchange.target + +.. include:: ../frags/regional-manual-use.rst |