Nexus Manual

9.1. Nexus Manual#

LibEuFin Nexus is an EBICS facilitator. It offers a command line interface to setup EBICS access, download banking records, and submit payments. LibEuFin Nexus is not a generic EBICS client but a Taler specific one.

Today, the LibEuFin implementation supports EBICS 3.0 and has been tested with Postfinance (CHF), GLS (EUR) and Maerki Baumann (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.

In this manual, we explain how to setup an EBICS subscriber. We assume that the bank has already granted EBICS access to the subscriber.

9.1.1. Installing Nexus#

The following section was tested on an OpenJDK 17 environment.

9.1.1.1. Installing the libeufin-nexus 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-nexus

9.1.1.2. Installing the libeufin-nexus 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.d/ubuntu.sources (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 Noble:

deb [signed-by=/etc/apt/keyrings/taler-systems.gpg] https://deb.taler.net/apt/ubuntu/ noble 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 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-nexus

9.1.1.3. Building from source#

Nexus 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-nexus command should be found in the $PATH.

9.1.2. Database setup#

The configuration file must include a connection string that tells Nexus how it should connect to the database. The default is:

[libeufin-nexusdb-postgres]
config = postgres:///libeufin

You must make sure that this database exists and is accessible to the user running Nexus before continuing. Then, the Nexus database schema must be created (or updated) to the current Nexus version using the following command:

$ libeufin-nexus-dbinit -c "$CONFIG_FILE"

where $CONFIG_FILE is again the path to a configuration that contains at least the above [libeufin-nexusdb-postgres] section.

9.1.3. Setting up the EBICS subscriber#

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 together with the name of the fiat currency.

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:

[nexus-ebics]
CURRENCY = CHF

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

Note

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

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.

9.1.3.1. Reuse existing client keys#

If you have client keys from a previous EBICS setup you can copy the JSON file to the configured path CLIENT_PRIVATE_KEYS_FILE (/var/lib/libeufin-nexus/client-ebics-keys.json with the default config).

Make sure this file is accessible to the user running libeufin-nexus, for the default services you should run:

$ chown libeufin-nexus:libeufin-nexus /var/lib/libeufin-nexus/client-ebics-keys.json

9.1.3.2. Create new client keys#

Assuming that the configuration file exists at $CONFIG_FILE, the following command should start the EBICS setup process:

$ libeufin-nexus ebics-setup -c "$CONFIG_FILE"

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.

9.1.3.3. Get bank keys#

Assuming that the configuration file exists at $CONFIG_FILE, the following command will finish the EBICS setup process:

$ libeufin-nexus ebics-setup -c "$CONFIG_FILE"

The EBICS setup is finished once the bank keys have been accepted.

Make sure this bank keys are accessible to the user running libeufin-nexus, for the default services you should run:

$ chown libeufin-nexus:libeufin-nexus /var/lib/libeufin-nexus/bank-ebics-keys.json

9.1.4. Sending payments#

Sending payments must follow a successful EBICS subscriber setup, where the bank obtained the subscriber keys, and the subscriber accepted the bank keys. Furthermore, the database has to be set up. Right now, some other process must queue payments to be submitted to the database, so this section only discusses how such queued payments will be executed.

The responsible subcommand for sending payments is ebics-submit, and its configuration is a superset of core-config. On top of that, it expects the database connection string and optionally a frequency at which it will check for submittable payments in the database.

The frequency may be specified as

[nexus-submit]
FREQUENCY = 5m

The supported time units are s (seconds), m (minutes), h (hours).

9.1.4.1. For testing#

The ebics-submit subcommand is not suitable to send arbitrary payments, but rather to submit initiated payments that are already queued for submission in the Nexus database.

Such queued payments may originate from bounces of incoming payments with a subject that would be invalid for a Taler withdrawal, or from a Taler exchange that needs to send a payment to a merchant.

For testing purposes it is possible to manually initiate a payment using the initiate-payment subcommand. The following invocation pays 1 CHF to the CH987654321 with an “Hello, Nexus!” subject:

$ libeufin-nexus initiate-payment -c "$CONFIG_FILE" --subject "Hello, Nexus!" "payto://iban/CH987654321?receiver-name=Name&amount=CHF:1"

$CONFIG_FILE is the path to Nexus’ configuration file and it does not need the FREQUENCY value. If the previous command worked, now the database should contain a new row in the initiated_outgoing_transactions table, with an unsubmitted submission state.

The following command would now pick such an unsubmitted initiated payment and send it to the bank.

$ libeufin-nexus ebics-submit -c "$CONFIG_FILE" --transient

The --transient flag instructs the software to perform only one pass on the database, submit what is submittable, and return.

The --debug-ebics $SAVEDIR flag will cause EBICS transactions steps and payloads to be stored in $SAVEDIR/$YYYY-MM-DD where $YYYY-MM-DD represents the date when the upload took place. This is mostly useful for debugging.

9.1.4.2. For production#

The ebics-submit subcommand can run in fixed frequency, or transient mode.

The fixed frequency mode causes the command to check the database every time the frequency period expires. To activate this mode, and – for example – set a frequency of five minutes, set the configuration value FREQUENCY to 5m. Assuming that FREQUENCY is set as described above, the following invocation would make ebics-submit check the database every five minutes, and submit any initiated payment according to their submission state.

$ libeufin-nexus ebics-submit -c "$CONFIG_FILE"

Transient mode causes ebics-submit to check the database only once, submit any initiated payment according to their submission state, and return.

$ libeufin-nexus ebics-submit -c "$CONFIG_FILE"

9.1.5. Downloading payment records#

Downloading payments must follow a successful EBICS subscriber setup, where the bank obtained the subscriber keys, and the subscriber accepted the bank keys. Furthermore, the database has to be set up.

The responsible subcommand for fetching and registering payments is ebics-fetch, and its configuration is a superset of core-config. On top of that, it expects the database connection string and optionally a frequency and a checkpoint time of day.

For the best user experience, new transactions should be registered as soon as they are booked. This is especially important for instant transactions, which reach final status in ~10 seconds. On the other hand, EBICS document fetches are slow and expensive and should not be performed more than necessary.

ebics-fetch will run a periodical fetch of pending documents (documents that have never been fetched before). If the bank server supports it, it will also listen to real-time document availability notifications and fetch documents as soon as they are announced. This enables instant registration of instant transactions. If your bank server does not support real-time notifications, it is recommended that you fetch more often; otherwise, you can reduce the fetch frequency.

Only fetching pending documents is not always reliable, if other EBICS clients use the same connection settings as libeufin-nexus, they can consume documents before they are ingested. In case of bank downtime, the status of documents can be lost. This is why ebics-fetch will run a checkpoint every day to download all documents generated since the last checkpoint.

If the bank supports real-time notifications, you can expect transactions to be registered as soon as they are booked: ~10s for instant transactions and 24 to 72h for other transactions. Otherwise, expect a latency corresponding to the fetch frequency for instant transactions. Thanks to checkpointing, latency should not exceed one day.

The frequency may be specified as

[nexus-fetch]
FREQUENCY = 5m

The supported time units are s (seconds), m (minutes), h (hours).

The checkpoint time of day may be specified as

[nexus-fetch]
CHECKPOINT_TIME_OF_DAY = 19:00

Assuming that $CONFIG_FILE contains all required options, the following command would download any unseen EBICS files:

$ libeufin-nexus ebics-fetch -c "$CONFIG_FILE" --transient

The ebics-fetch subcommand will always cause libeufin-nexus to download then parse EBICS files and register their content statements into its local database.

The --transient flag makes the command download and import EBICS files only once and return immediately afterwards. Without the flag, Nexus will download at the frequency specified in the configuration or when it receive real time notifications.

The --debug-ebics $SAVEDIR flag will cause EBICS transactions steps and payloads to be stored in $SAVEDIR/$YYYY-MM-DD where $YYYY-MM-DD represents the date when the download took place. This is mostly useful for debugging.

9.1.5.1. For Testing#

If the bank account history has transactions that are useful for testing, it is possible to re-download them via the --pinned-start argument.

The following command redownloads transactions from the pinned start until the present:

$ libeufin-nexus ebics-fetch -c "$CONFIG_FILE" --pinned-start 2023-11-01

Note

If the Nexus database already contains the bank account history, you might need to reset the database in order to have the re-downloaded transactions be properly registered.

Be careful when resetting the database: resetting the wrong database might cause DATA LOSS!

Use the IGNORE_BOUNCES_BEFORE configuration to prevent malformed transactions from being bounced a second time when they are registered again.

9.1.6. Manual balance adjustement#

As LibEuFin Nexus is a Taler-specific EBICS client, it ignores non-payment transactions. This means that certain debits from your banks for fees or taxes can be ignored. This imply that the actual balance of your bank account may deviate from that expected by Taler Exchange, leading to Exchange bankruptcy.

To fix this, you must periodically send administrative balance adjustment transfers conaining “ADMIN BALANCE ADJUST” in their subject.

9.1.7. Manual EBICS import & export#

If your bank does not support the EBICS protocol, but has an interface for importing and exporting ISO20022 files, you can run the deployment manually.

9.1.7.1. Sending payments#

To obtain PAIN files for pending initiated outgoing transactions in a payments.zip file, you can run :

$ libeufin-nexus manual export -c "$CONFIG_FILE" payments.zip

Each file in the ZIP file corresponds to a single batch of transactions. The command prints the details of each batch and their internal transactions. Files are generated as if they would be uploaded using the EBICS protocol.

As we have no way of knowing whether the upload was successful, you need to update the batch status manually. Until you tell libeufin-nexus that a batch has been uploaded successfully, it will re-export it next time.

If the batch has been uploaded successfully, you can run this command:

$ libeufin-nexus manual status -c "$CONFIG_FILE" batch $BATCH_ID pending

Alternatively, if the error is transient, for example if the bank’s user interface is under maintenance, you can set a temporary error accompanied by a message with:

$ libeufin-nexus manual status -c "$CONFIG_FILE" batch $BATCH_ID transient_failure "In maintenance until Wednesday morning"

If the error is permanent, for example if the file is malformed and your bank will never accept it, you can define a permanent error with:

$ libeufin-nexus manual status -c "$CONFIG_FILE" batch $BATCH_ID permanent_failure "Unuspported transaction kind"

It can also happen that a batch is partially successful, the batch is uploaded but some transactions failed, for example because a creditor’s IBAN is incorrect. You can mark a batch as uploaded even though some transactions have failed with:

$ libeufin-nexus manual status -c "$CONFIG_FILE" batch $BATCH_ID pending
$ libeufin-nexus manual status -c "$CONFIG_FILE" tx $TX_ID permanent_failure "Malformed IBAN"

Successful transactions should be announced in CAMT files, so you shouldn’t have to mark them as successful manually, but you still can with:

$ libeufin-nexus manual status -c "$CONFIG_FILE" tx $TX_ID success

9.1.7.2. Import payment record#

To import CAMT files, you can run:

$ libeufin-nexus manual import -c "$CONFIG_FILE" camt53.xml

Files will be processed as if they had been downloaded using the EBICS protocol.