.. target audience: operator, developer

Bank Setup Manual
#################

.. contents:: Table of Contents

LibEuFin Bank implements a simple core banking system with
account and REST APIs, including REST APIs for a Web interface
and REST APIs to interact with GNU Taler components.

In this manual, we explain how to setup a bank.

Installing LibEuFin Bank
========================

The following section was tested on an *OpenJDK 17* environment.

Building from source
--------------------

Bank belongs to the LibEuFin project, and can be downloaded via Git:

.. code-block:: console

  $ git clone git://git.taler.net/libeufin

Note that Kotlin and Gradle should already work on the host system.

Navigate into the *libeufin* local repository, and from top-level run:

.. code-block:: console

  $ ./bootstrap
  $ ./configure --prefix=$PREFIX
  $ make install

If the previous steps succeeded, the ``libeufin-bank`` command should
be found in the $PATH.

Setting up the LibEuFin Bank
============================

The following snippet shows the mandatory configuration values:

.. code-block:: ini

  [libeufin-bank]
  CURRENCY = KUDOS

  # Server
  SERVE = tcp
  PORT = 8080

  [libeufin-bankdb-postgres]
  CONFIG = postgresql:///libeufinbank

.. note::
  Refer to the manpage ``libeufin-man.conf(5)``
  for the full array of configuration values.

Assuming that the configuration file exists at ``$config_file``, the following
command would define the database schema and create an admin account.

.. code-block:: console

  $ libeufin-bank dbinit -c $config_file

If you wish to authenticate as admin, you must change the account password with the following command.

.. code-block:: console

  $ libeufin-bank passwd -c $config_file admin $PASSWORD

Then you can start the HTTP server.

.. code-block:: console

  $ libeufin-bank serve -c $config_file


Using custom e-mail / SMS TAN scripts
-------------------------------------

The guided setup installs the TAN scripts found in ``libeufin/contrib/``:
``libeufin-tan-email.sh`` and ``libeufin-tan-sms.sh``, but should you want to
use custom scripts to send the e-mail or SMS TAN, set the configuration like
follows:

.. note::

  The default SMS TAN script is based on the `Telesign <https://www.telesign.com>`_ provider.

.. code-block:: ini

  [libeufin-bank]

  TAN_SMS = custom-tan-sms.sh
  TAN_EMAIL = custom-tan-email.sh

The scripts TAN_SMS/EMAIL must accept the phone number / e-mail address as the
``$1`` parameter and the message content to be transmitted in their standard
input.


Using the Bank Web Interface
============================

Before you can use the Web interface, you must set
a password for the "admin" account. You can do this
using:

.. code-block:: console

  $ libeufin-bank passwd -c $config_file admin "$PASSWORD"

Setting up Accounts
-------------------

Using the above "$PASSWORD", log into the Web interface as "admin". Then
search for the button "Create account" near the list of all existing bank
accounts in the Web interface of libeufin-bank.

You will be asked to specify:

Username
  A unique account name the user will use to access the bank account.

Name
  Legal name of the user or business owning the account.

Email
  E-mail address of the account owner. Can be used to send a TAN message for 2-factor authentication (if enabled).

Phone
  Mobile phone number of the account owner. Can be used to send a TAN message for 2-factor authentication (if enabled).

Max debt
  Maximum amount the account is allowed to go into debt. Non-zero settings **must** be used for the "admin" account where this setting effectively creates a limit on the amount of money managed by the bank.

Is this a Taler Exchange?
  Should be disabled except if you are setting up an account for a GNU Taler exchange. If enabled, transactions that are not compatible with a GNU Taler exchange will be automatically refused by the bank.

XXX Cashout channel
  Used in a regional currency setup to specify the external account number of a bank account in fiat currency that belongs the merchant. Allows the merchant to exchange its regional currency money for wire transfers in fiat currency into this account. Optional. Not available unless the bank is configured for regional currencies.

Is this account public?
  Public accounts can be viewed without access control, their balance and transaction history becomes public.

After submitting the form, a randomly created password
for the new account will be shown in a notification.
The administrator can also change passwords for any
account in the system using the "change password" link
in the account list. To change other details about an
account, select the "Username" in the account list.


Account Introspection
---------------------

Users can see (and possibly change) the settings of
their bank account and also their IBAN by clicking
on the "Welcome, $USERNAME" text after logging into
their bank account using their username and password.

The IBAN field has a convenient "copy to clipboard"
button next to it.


Making Transfers between Accounts
---------------------------------

First, you need to know the IBAN of the account to credit, and log in as the
user of the account to be debited. Then select "Using a form", enter the IBAN
under "Recipient" and specify a wire transfer subject and the total amount to
be wired. After pressing "Send", you may have to pass a 2-FA check.


Integration with the Taler Exchange
===================================

Exchange Configuration
----------------------

TODO.

Withdrawing e-cash to a Taler wallet
------------------------------------

TODO.