..
  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, developer

.. _libeufin-nexus:

Nexus Manual
############

LibEuFin Nexus is an EBICS facilitator.  It offers a command line interface to
setup EBICS access, download banking records, and submit payments.  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.

Future versions will offer a Web API to allow Taler exchanges to talk to their
banks.

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

.. contents:: Table of Contents
  :local:


Installing Nexus
================

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


Installing the libeufin-nexus binary packages on Debian
-------------------------------------------------------

.. include:: ../frags/installing-debian.rst

.. include:: ../frags/apt-install-libeufin-nexus.rst


Installing the libeufin-nexus binary packages on Ubuntu
-------------------------------------------------------

.. include:: ../frags/installing-ubuntu.rst

.. include:: ../frags/apt-install-libeufin-nexus.rst


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

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

.. _ebics-setup:

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.

The following snippet shows the mandatory configuration values:

.. _core-config:

.. code-block:: ini

  [nexus-ebics]
  CURRENCY = CHF

  # Bank
  HOST_BASE_URL = http://bank.example.com/
  BANK_DIALECT = postfinance

  # EBICS IDs
  HOST_ID = mybank
  USER_ID = myuser
  PARTNER_ID = myorg

  # Account information
  IBAN = myiban
  BIC = mybic
  NAME = myname

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

.. note::
  If you want to use existing client keys, copy the JSON file to the configured path ``CLIENT_PRIVATE_KEYS_FILE`` (``/var/lib/libeufin-nexus/client-ebics-keys.json`` by default) before running the following commands.

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

.. code-block:: console

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

If the previous command failed when running EBICS INI with an error code of
``EBICS_INVALID_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, run the same
command again to download and verify the bank's keys:

.. code-block:: console

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

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


Database setup
==============

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

.. code-block:: ini

  [nexus-postgres]
  config = postgres:///nexus

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:

.. code-block:: console

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

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

.. _sending-payments:

Sending payments
================

Sending payments must follow a successful `EBICS subscriber setup
<ebics-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

.. code-block:: ini

  [nexus-submit]
  FREQUENCY = 5m

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


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:

.. code-block:: console

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


.. code-block:: console

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

Alternatively, the ``--debug`` flag makes ebics-submit accept data from STDIN,
and submit it to the bank.

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.

.. code-block:: console

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

.. code-block:: console

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


.. _receive-transaction-data:

Downloading payment records
===========================

Downloading payments must follow a successful `EBICS subscriber setup
<ebics-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 sending 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 at which it will
downloads any unseen notifications and ingest them in the database.

The frequency **may** be specified as

.. code-block:: ini

  [nexus-fetch]
  FREQUENCY = 5m

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

Assuming that ``$CONFIG_FILE`` contains all required options, the following command
would download any unseen notifications (as ``camt.054`` files):

.. code-block:: console

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

The ``ebics-fetch`` subcommand will always cause libeufin-nexus to download
the transaction data, parse the CAMT files and import the statements into its
local database.

The ``--transient`` flag makes the command download and import transaction
data only once and return immediately afterwards.  Without the flag, Nexus
will download the transaction records at the frequency specified in the
configuration.

The ``--debug-ebcis`` flag will cause the CAMT files to be stored in
``$LIBEUFIN_DATA_HOME/camt/$YYYY-MM-DD`` where ``$YYYY-MM-DD`` represents the
date when the download took place. This is mostly useful for debugging.




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:

.. code-block:: console

  $ libeufin-nexus ebics-fetch -c "$CONFIG_FILE" --pinned-start 2023-06-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 ingested. Be careful when resetting the database: resetting the wrong
  database might cause DATA LOSS!