.. target audience: operator Regional Currency Setup Manual ############################## .. contents:: Table of Contents GNU Taler can be used to operate a regional currency. For this, LibEuFin Bank is setup to operate bank accounts in the regional currency that ultimately interact with the GNU Taler exchange. Optionally, LibEuFin Nexus can be used to integrate with the traditional core banking system, and then the LibEuFin Conversion triggers help convert fiat currency to regional currency and vice versa. Conversion rates and limits can be applied when converting between the regional currency and the fiat currency. In this manual, we explain how to setup such a regional currency. Guided basic setup ================== Prerequisites ------------- For this manual, we assume that the system is deployed on a contemporary Debian GNU/Linux or Ubuntu LTS system using the binary packages provided. Furthermore, you should run the process on a system with one or more globally reachable IP address(es) *and* with various DNS names already pointing to these IPs. To further simplify the process, we suggest to use (or at least study) the automatic deployment scripts provided in the ``deployment.git`` Git repository in the ``regional-currency/`` folder. Obtaining the scripts --------------------- First, download the deployment scripts via Git: .. code-block:: console $ git clone git://git.taler.net/deployment Guided Configuration -------------------- This approach sets up a regional currency with cash-in/-out rates of 1:1. Navigate into the *regional-currency/* directory, and as **root** run: .. code-block:: console # ./main.sh The script will start by asking you fundamental questions about the desired setup, in particular: * The name of the regional currency. It must have 3 to 11 letters. Currently only 'NETZBON' is supported. * The name of the regional currency bank. It will be shown to business users when they interact with the system. * Whether to use TLS or not. You should answer ``y`` in most cases. * Whether to run taler-exchange-offline. Unless you need a high-security setup and expect to run an offline key management process, say ``y``. If you say ``n``, you will need to run ``taler-exchange-offline setup`` on your offline system and provide the master public key. Furthermore, you should then study the exchange manual on offline key management to finish the exchange setup process later. * The admin password for the bank. Be absolutely sure to enter a very, very long and high-entropy password, preferably generated by a tool like "uuidgen". * The DNS domain name of your setup (i.e: domain.tld). The installer will create by itself all the needed subdomains for your domain name, as (``bank.$DOMAIN``, ``exchange.$DOMAIN`` and ``backend.$DOMAIN``). But, these subdomain names, must have been added beforehand to your DNS domain control panel, and they must be pointing to the IP address of the system on which you are running the installation (before you execute the installer)). The information you entered will be stored in a file called ``config/user.conf``. Should you run the script in the future (for example, to upgrade the installation), you will not be asked these questions a second time. After answering all of the questions, the actual installation will start. The scripts will download and configure various packages, which may take some time. Grab a coffee. .. note:: At this point, the setup is NOT connected to any fiat bank account! Connecting to a Fiat Bank ========================= Some regional currencies are backed by assets in a fiat currency and allow users to convert fiat currency into the regional currency (``cash in``) and to convert regional currency into fiat currency (``cash out``). Restrictions, exchange rates and fees may apply to these conversions. This section explains how to setup LibEuFin Nexus to communicate with the fiat bank account that backs the regional currency. Prerequisites ------------- You must have a bank account at a bank dealing in fiat currency that offers an online banking protocol supported by LibEuFin Nexus. As legacy transactions in that bank account would likely confuse the system, it is highly advised to use a fresh bank account, with an empty transaction history. 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. EBICS setup ----------- Follow the instructions from :ref:`EBICS subscriber setup ` to configure the LibEuFin Nexus for access to your fiat bank account, but do edit the config file at ``/etc/libeufin/libeufin-nexus.conf``, since the other components expect it. .. note:: For debug setups where the cash-ins are simulated :ref:`this way `, this step can be entirely skipped. Configuring the merchant ======================== In order to setup a shop, you need a merchant backend to run. The guided setup installs and sets one backend up, but the user is required to complete the shop configuration via the Web browser. One fundamental piece of information are the banking details, to allow merchant receive payments from the exchange. If you don't have a bank account at the regional bank, contact the administrator and get one. After being able to login to the new bank account, you can see your IBAN by clicking on the ``Welcome, $USERNAME`` message in the profile page. The IBAN is shown under the ``Internal IBAN`` box. Next, point your browser to ``$proto://backend.$domain_name/``. You should be welcomed by the following merchant backoffice page: .. image:: merchant_first_login.png Such page offers to create a merchant profile: fill any required field (including your access token) and clik to ``confirm``. It should now be possible to associate the banking details to the profile just created: click to ``Bank account`` at the left of the page. The following page should be shown: .. image:: no_default_account_yet.png Click on the blue "+" sign on the top right of the page, and expect the following page to appear: .. image:: enter_instance_details.png This tutorial is focused on IBAN, so choose ``iban`` as the account type, and expect the following page to appear: .. image:: instance_iban_config.png After providing the details and confirming, the shop is ready to generate orders and accept payments. Make an order ------------- Click on ``Orders`` at the top left corner of the merchant backoffice page; the following page should appear .. image:: create_orders.png After having filled the required fields, the interface should show the following page with the related links to check the status of the order and let wallets pay for it. Take note of the link beside ``Payment URI`` (we'll call it ``$payUri``). .. image:: payment_links.png In order to test the setup, it should be now possible to use the command line wallet to withdraw Taler coins and spend them to buy the order we just created. .. _withdraw-simulation: Pay for the order ----------------- This section explains how to pay for the order in a scenario where the fiat bank is simulated. The simulation takes place by crafting ad-hoc XML files as if the bank would have issued them. Such XML files carry information about incoming payments to the regional currency master bank account. Finally, the XML files are passed to LibEuFin nexus via a convenient CLI method. The responsible script for such simulation is ``withdraw.sh``. Run ``./withdraw.sh`` without any arguments. Assuming that you ran the command as the ``test-user``, after the execution, 5 units of the regional currency should be found in the CLI wallet owned by ``test-user``. Check it with: .. code-block:: console $ taler-wallet-cli balance If so, call the wallet in the following way to finally pay for the order just created: .. code-block:: console $ taler-wallet-cli handle-uri $payUri .. note:: Reset the state before going to production, as it impacts the way nexus asks records to the bank. In particular, delete: any database and the files ``config/user.conf`` and ``config/internal.conf``, and finally run ``./main.sh`` again. .. FIXME: uncomment once tested. Enable regional currency conversion =================================== Prerequisites ------------- This step assumes that you already have a working regional currency bank and have successfully connected to a backing fiat bank account. Additionally, for each account that is allowed to convert regional currency into fiat, you must configure the (fiat) bank account number of the fiat currency with the respective account profile. Only the bank ``admin`` is allowed to set fiat bank account numbers. Furthermore, to achieve a reasonable security level, you must enable two factor authentication for "cash out" transactions. This requires you to configure an e-mail address or phone number for every account that supports "cash out" transactions --- and to setup your system for sending e-mails or SMS. This manual does not cover setting up e-mail. For SMS delivery, you will need to obtain credentials from an SMS provider and provide a script to send messages via such a provider. Configuration ------------- You have to enable conversion and at least one TAN channel for cashout in the ``/etc/libeufin/libeufin-bank.conf`` configuration file: .. code-block:: console [libeufin-bank] ALLOW_CONVERSION = yes FIAT_CURRENCY = EUR TAN_SMS = libeufin-tan-sms.sh # And/Or TAN_EMAIL = libeufin-tan-email.sh Afterwards, restart the bank: .. code-block:: console # systemctl restart libeufin-bank The scripts TAN_SMS/EMAIL must accept the phone number / e-mail address as the ``$1`` parameter and the content in their standard input. The LibEuFin repository offers them in ``contrib/``: adjust to your setup! .. note:: the TAN_SMS script relies on a Telesign account. For this reason, it needs a telesign-secret file found in the PATH, that defines the environment variables API_KEY and CUSTOMER_ID Web-based Configuration ----------------------- Now you should be able to setup conversion rates and ``admin`` debt limit though the Web interface of the bank as the ``admin`` user. Conversion ON! -------------- The last step is to enable the Nexus services to import incoming bank transactions (cash in) and to trigger outgoing bank transactions (cash out): .. code-block:: console # systemd enable --now libeufin-nexus-ebics-fetch # systemd enable --now libeufin-nexus-ebics-submit Going live! =========== Exchange setup -------------- First, you 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" \ 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. Wallet setup ------------ 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`` URL or by manually entering the URL into the respective ``Add exchange`` dialogue. With this, you should then be able to ``add`` funds in the regional currency to your exchange by starting the withdraw process in the wallet. After specifying the desired amount, the wallet should show you the details of the fiat wire transfer that must be made for the cash in to be completed. Once the money has arrived at the fiat bank account, Nexus will obtain the transaction data and the regional currency bank will create the corresponding amount in regional currency, crediting the GNU Taler exchange account. In turn, the exchange will issue the respective amount to your wallet. For testing, you should be able to *deposit* regional currency directly into a LibEuFin Bank account from the Taler wallet. Once the exchange has credited the regional currency account, log into the bank account using the Web interface. Assuming the cash out rules are satisfied, you should then be able to start a cash out operation. This will trigger a transfer from your regional currency account to the regional currency master ``bank`` account which will effectively destroy the respective amount of regional currency. The conversion triggers will inform Nexus about the destruction, and Nexus will then wire the corresponding amount in fiat to the associated fiat bank account.