diff options
Diffstat (limited to 'libeufin/nexus-manual.rst')
| -rw-r--r-- | libeufin/nexus-manual.rst | 237 |
1 files changed, 146 insertions, 91 deletions
diff --git a/libeufin/nexus-manual.rst b/libeufin/nexus-manual.rst index bc4ca471..de2f4bae 100644 --- a/libeufin/nexus-manual.rst +++ b/libeufin/nexus-manual.rst @@ -1,23 +1,68 @@ +.. + 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 ############ -.. contents:: Table of Contents +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. -LibEuFin Nexus is an EBICS facilitator. It offers a command line -interface to setup EBICS access, download banking records, and submit payments. -Future versions will offer a Web API to allow Taler Exchanges to talk to their +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 had already granted EBICS access to the subscriber. +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 -------------------- @@ -45,71 +90,79 @@ be found in the $PATH. Setting up the EBICS subscriber =============================== -.. include:: ../frags/ebics-setup.rst - -Sending payments -================ +.. include:: ../frags/nexus-ebics-setup.rst -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. 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 to check -for submittable payments in the database. +Database setup +============== -The connection string is specified as +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 - # Optional, but useful to check what Nexus sends to the bank - submissions_log_directory = $LIBEUFIN_DATA_HOME/uploads + FREQUENCY = 5m The supported time units are ``s`` (seconds), ``m`` (minutes), ``h`` (hours). -Before delving into the following sections, the database schema must be -created, therefore run the following command: - -.. code-block:: console - - $ libeufin-nexus dbinit -c $config_file - -Where ``$config_file`` is the path to a configuration path that contains at -least the ``[nexus-postgres]`` section. For testing ----------- The ``ebics-submit`` subcommand is **not** suitable to send arbitrary -payments, but rather to submit initiated payments that may be found -in the database. - -Such initiated payments may be refunds of incoming payments with a subject -that would be invalid for a Taler withdrawal, or from a Taler exchange in -the attempt to pay a merchant. +payments, but rather to submit initiated payments that are already queued for +submission in the Nexus database. -For testing purposes, however, it is possible to artificially initiate -a payment into the database with the ``contrib/payment_initiation_debug.sh`` -script, found in the libeufin repository. The script pays always one Swiss -Franc to an IBAN and subject pair of choice. +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. +subject: .. code-block:: console - $ ./payment_initiation_debug.sh $config_file CH987654321 "Hello, Nexus!" + $ 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 +``$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. @@ -120,13 +173,14 @@ send it to the bank. .. code-block:: console - $ libeufin-nexus ebics-submit -c $config_file --transient + $ 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. +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 -------------- @@ -136,87 +190,88 @@ 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 -``$config_fixed_frequency`` is set as described above, the following invocation would +``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_fixed_frequency - + $ 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 + $ libeufin-nexus ebics-submit -c "$CONFIG_FILE" + + +.. _receive-transaction-data: -Downloading records -=================== +Downloading payment records +=========================== -Downloading records must follow a successful `EBICS subscriber setup <ebics-setup>`_, -where the bank obtained the subscriber keys, and the subscriber accepted the bank keys. +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 configuration file must contain all the ``[ebics-setup]`` sections, plus the following -values to set the database connection and a log directory where any downloaded record would -be stored. +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-postgres] - config = postgres:///nexus [nexus-fetch] - # Optional, but usefull against data loss. - statement_log_directory = $LIBEUFIN_DATA_HOME/downloads + FREQUENCY = 5m -Assuming that ``$config_file`` contains any required option, the following command -would download any unseen notifications (as camt.054 files). +The supported time units are ``s`` (seconds), ``m`` (minutes), ``h`` (hours). -.. code-block:: console +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 +.. code-block:: console -The ``--transient`` flag makes the command to download only once and return. If the -bank returned any records, look in ``$LIBEUFIN_DATA_HOME/camt/YYYY-MM-DD`` to find them. -YYYY-MM-DD is the date when the download took place. + $ libeufin-nexus ebics-fetch -c "$CONFIG_FILE" --transient -To activate periodic downloads, add the following setting to the ``nexus-fetch`` -configuration section in ``$config_file``: +The ``ebics-fetch`` subcommand will always cause libeufin-nexus to download +then parse EBICS files and ingest their content statements into its local +database. -.. code-block:: ini +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: - [nexus-fetch] - frequency = 5m +* ``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 following invocation would then download records every five minutes, asking the bank -to only return documents that are timestamped *from* (inclusive) the last incoming transaction. +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. -.. code-block:: console +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. - $ libeufin-nexus ebics-fetch -c $config_file -Testing -------- +For Testing +----------- If the bank account history has transactions that are useful for testing, it is -possible to redownload them via the ``--pinned-start`` argument. Note: if the Nexus -database contains already the bank account history, you might need to **reset** it, -in order to have the redownloaded transactions ingested. +possible to re-download them via the ``--pinned-start`` argument. -.. note:: - - Double-check the configuration: resetting the wrong database might cause DATA LOSS! - -For example, say that three back on the 2023-06-01 an handful of incoming transactions -got booked at the bank account watched by Nexus. After such day, the following command -would redownload them (and ingest them, if the database doesn't have them): +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 - + $ libeufin-nexus ebics-fetch -c "$CONFIG_FILE" --pinned-start 2023-11-01 .. note:: - The command redownloads transactions *from* the pinned start until the present. + 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! |