diff options
Diffstat (limited to 'libeufin/nexus-manual.rst')
| -rw-r--r-- | libeufin/nexus-manual.rst | 277 |
1 files changed, 277 insertions, 0 deletions
diff --git a/libeufin/nexus-manual.rst b/libeufin/nexus-manual.rst new file mode 100644 index 00000000..de2f4bae --- /dev/null +++ b/libeufin/nexus-manual.rst @@ -0,0 +1,277 @@ +.. + 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 +=============================== + +.. include:: ../frags/nexus-ebics-setup.rst + +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. + +The ``--debug-ebics $SAVEDIR`` flag will cause the files to be stored in +``$SAVEDIR/$YYYY-MM-DD/submit`` where ``$YYYY-MM-DD`` represents the +date when the upload took place. This is mostly useful for debugging. + +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 new EBICS files 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 EBICS files: + +.. code-block:: console + + $ libeufin-nexus ebics-fetch -c "$CONFIG_FILE" --transient + +The ``ebics-fetch`` subcommand will always cause libeufin-nexus to download +then parse EBICS files and ingest their content statements into its local +database. + +The files type can be given as an argument to select what will be fetched. If no argument is given, all supported files are fetched. The following files are supported: + +* ``acknowledgement``: EBICS acknowledgement, retrieves the status of EBICS orders. +* ``status``: Payment status, retrieves status of pending debits. +* ``notification``: Debit & credit notifications, retrieves the history of confirmed debits and credits. + +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. + +The ``--debug-ebics $SAVEDIR`` flag will cause the files to be stored in +``$SAVEDIR/$YYYY-MM-DD/fetch`` 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-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 ingested. Be careful when resetting the database: resetting the wrong + database might cause DATA LOSS! |