nexus submit manual

1 files changed, 113 insertions, 0 deletions

diff --git a/libeufin/nexus-manual.rst b/libeufin/nexus-manual.rst
index 70ac5e05..90cc1e56 100644
--- a/libeufin/nexus-manual.rst
+++ b/libeufin/nexus-manual.rst
@@ -40,11 +40,15 @@ Navigate into the *libeufin* local repository, and from top-level run:
 If the previous steps succeeded, the ``libeufin-nexus`` command should
 be found in the $PATH.
 
+.. _ebics-setup:
+
 Setting up the EBICS subscriber
 ===============================
 
 The following snippet shows the mandatory configuration values.
 
+.. _core-config:
+
 .. code-block:: console
 
   [nexus-ebics]
@@ -98,3 +102,112 @@ order to download the bank keys and let the user accept them.
   libeufin-nexus ebics-setup -c $config_file
 
 The setup is considered finished once the user accepts the bank keys.
+
+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.  The responsible subcommand 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.
+
+The connection string is specified as
+
+.. code-block:: console
+  
+  [nexus-postgres]
+
+  config = postgres:///nexus
+
+The frequency **may** be specified as
+
+.. code-block:: console
+  
+  [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 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.
+
+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.
+
+The following invocation pays 1 CHF to the CH987654321 with an "Hello, Nexus!"
+subject.
+
+.. code-block:: console
+
+  ./payment_initiation_debug.sh $config_file CH987654321 "Hello, Nexus!"
+
+``$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.
+
+For production
+--------------
+
+The ``ebics-submit`` subcommand can run in long-polling, fixed frequency, or
+transient mode.
+
+The long-polling mode causes the command to never return and to submit the payments
+to the bank *as soon as they arrive in the database*.  To activate this mode, set
+the frequency to ``0s`` in the configuration.  Assuming that ``$config_long_polling``
+is set as described above, the following invocation would make ``ebics-submit`` run
+in long-polling mode:
+
+.. code-block:: console
+
+  libeufin-nexus ebics-submit -c $config_file
+
+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
+make ``ebics-submit`` check the database every five minutes, and submit any initiated
+payment according to their submission state.
+
+.. note::
+
+  long-polling is still unsupported and resubmission of payments with a
+  ``transient_failure`` after a long-polled trigger is under discussion.
+
+.. code-block:: console
+
+  libeufin-nexus ebics-submit -c $config_fixed_frequency
+
+
+Finally, transient mode causes ``ebics-submit`` to check the database only once,
+submit any initiated payment according to their submission state, and soon return.
+
+.. code-block:: console
+
+  libeufin-nexus ebics-submit -c $config
+
+There's no need to set the frequency in the configuration.