11.2. Bank Setup Manual¶

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.

11.2.1. Installing LibEuFin Bank ¶

The following section was tested on an OpenJDK 17 environment.

11.2.1.1. Installing the libeufin-bank binary packages on Debian ¶

To install the GNU Taler Debian packages, first ensure that you have the right Debian distribution. At this time, the packages are built for Debian bookworm.

You need to add a file to import the GNU Taler packages. Typically, this is done by adding a file /etc/apt/sources.list.d/taler.list that looks like this:

deb [signed-by=/etc/apt/keyrings/taler-systems.gpg] https://deb.taler.net/apt/debian bookworm main

Next, you must import the Taler Systems SA public package signing key into your keyring and update the package lists:

# wget -O /etc/apt/keyrings/taler-systems.gpg \
    https://taler.net/taler-systems.gpg
# apt update

Note

You may want to verify the correctness of the Taler Systems SA key out-of-band.

Now your system is ready to install the official GNU Taler binary packages using apt.

To install libeufin-nexus, you can now simply run:

# apt install libeufin-bank

11.2.1.2. Installing the libeufin-bank binary packages on Ubuntu ¶

To install the GNU Taler Ubuntu packages, first ensure that you have the right Ubuntu distribution. At this time, the packages are built for Ubuntu Lunar and Ubuntu Jammy. Make sure to have universe in your /etc/apt/sources.list (after main) as we depend on some packages from Ubuntu universe.

A typical /etc/apt/sources.list.d/taler.list file for this setup would look like this for Ubuntu Lunar:

deb [signed-by=/etc/apt/keyrings/taler-systems.gpg] https://deb.taler.net/apt/ubuntu/ lunar taler-lunar

For Ubuntu Mantic use this instead:

deb [signed-by=/etc/apt/keyrings/taler-systems.gpg] https://deb.taler.net/apt/ubuntu/ mantic taler-mantic

The last line is crucial, as it adds the GNU Taler packages.

Next, you must import the Taler Systems SA public package signing key into your keyring and update the package lists:

# wget -O /etc/apt/keyrings/taler-systems.gpg \
    https://taler.net/taler-systems.gpg
# apt update

Note

You may want to verify the correctness of the Taler Systems key out-of-band.

Now your system is ready to install the official GNU Taler binary packages using apt.

To install libeufin-nexus, you can now simply run:

# apt install libeufin-bank

11.2.1.3. Building from source ¶

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

$ 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:

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

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

11.2.2. Minimal Configuration for LibEuFin Bank ¶

The following snippet shows the mandatory configuration values:

[libeufin-bank]
CURRENCY = KUDOS

# Supported payment target type
WIRE_TYPE = iban or x-taler-bank
# If WIRE_TYPE = iban
IBAN_PAYTO_BIC = SANDBOXX
# If WIRE_TYPE = x-taler-bank
X_TALER_BANK_PAYTO_HOSTNAME = https://bank.taler.net

Note

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

11.2.2.1. Configuring multi-factor authentication ¶

libeufin-bank supports two-factor authentication. libeufin-bank uses helper scripts to send challenge codes to addresses for multi-factor authentication. We provide two default helper scripts: libeufin-tan-email.sh to send e-mails and libeufin-tan-sms.sh to send SMS. To enable two-factor authentication you need to configure at least one TAN channel.

11.2.2.1.1. SMS TAN channel ¶

The default libeufin-tan-sms.sh script is based on the Telesign SMS provider. It requires an additional AUTH_TOKEN environment variable for Telesign Basic authentication.

To test your setup run:

$ AUTH_TOKEN=$TELESIGN_TOKEN
$ echo "Test 1234" | libeufin-tan-sms.sh $PHONE

If you received an SMS containing “Test 1234” you can enable this channel in the config:

[libeufin-bank]
TAN_SMS = libeufin-tan-sms.sh
TAN_SMS_ENV = "AUTH_TOKEN=$TELESIGN_TOKEN"

11.2.2.1.2. Mail TAN channel ¶

The default libeufin-tan-email.sh script is based on the mail Linux command. It requires a working local mail transfer agent.

To test your setup run:

$ echo "Test 1234" | libeufin-tan-email.sh $EMAIL

If you received an email containing “Test 1234” you can enable this channel in the config:

[libeufin-bank]
TAN_EMAIL = libeufin-tan-email.sh

11.2.2.1.3. Custom TAN channel scripts ¶

It is possible to replace these scripts with use custom scripts to send the e-mail or SMS TAN. Such alternative scripts must accept the phone number / e-mail address as the $1 parameter and the message content to be transmitted in their standard input. They should return 0 to indicate successful transmission of the challenge and non-zero on failure.

To change the scripts used for multi-factor authentication, change the following options in the configuration file:

[libeufin-bank]
TAN_SMS = custom-tan-sms.sh
TAN_SMS_ENV =
TAN_EMAIL = custom-tan-email.sh
TAN_EMAIL_ENV =

11.2.3. Launching libeufin-bank ¶

Assuming that the configuration file exists at $CONFIG_FILE, the following command initializes (or upgrades) the database schema:

$ libeufin-bank-dbinit -c "$CONFIG_FILE"

Once this is done, you can start the libeufin-bank HTTP server:

$ libeufin-bank serve -c "$CONFIG_FILE"

11.2.4. Using the bank Web interface ¶

To be able to use the Web interface, you must set a password for the “admin” account. You can set (or reset) the account password to $PASSWORD using the following command:

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

You can also use the same command to reset the passwords of other accounts by replacing “admin” with the respective login.

11.2.4.1. Setting up accounts ¶

Using the above “$PASSWORD”, log into the Web interface as “admin”. To setup regular accounts, 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.

11.2.4.2. 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.

11.2.4.3. 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.

11.2.5. Integration with the Taler Exchange ¶

Note

This step is fully automated if you use the automated setup manual.

You must have an exchange account with username exchange for conversion to work. Assuming that the configuration file exists at $CONFIG_FILE, the following command would create one:

$ libeufin-bank create-account '{"username":"exchange","password":"$EXCHANGE_PASSWORD","name":"Cashout Exchange","is_taler_exchange":true}' -c "$CONFIG_FILE"

Note

You can also set up the exchange account as “admin” using the Web interface of libeufin-bank.

Having done so, take note of two key pieces of information, namely the $EXCHANGE_PASSWORD and the “payto://”-URI of the exchange bank account. This information must then be used to configure the exchange as described in exchange bank account configuration. When using the libeufin-bank in the context of a regional currency with conversion, you must additionally specify a “conversion-url” when setting up the exchange account. See the section on conversion setup in the regional currency setup chapter for details.

11.2.6. Withdrawing e-cash to a Taler wallet ¶

Note

This step is fully automated if you use the automated setup manual.

Users can withdraw digital cash from their bank account starting from their online banking as implemented by the libeufin-bank. However, in this scenario, the Taler wallet may not already know about an exchange that works with the respective currency. Thus, the protocol includes the possibility of the bank recommending an exchange service to the wallet, thus providing a sane default for the wallet to suggest to the user. To do so, the base URL of the exchange API must be specified in the libeufin-bank configuration:

[libeufin-bank]
DEFAULT_EXCHANGE=${PROTO}://exchange.${DOMAIN_NAME}

After changing this value, the libeufin-bank service needs to be restarted to make the change effective.

Note

The user may change the default exchange from within the wallet, assuming they know of an alternative exchanges for the currency.

11.1. Nexus Manual

11.3. Regional Currency Automated Setup Manual