[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[taler-docs] branch master updated: nexus submit manual
From: |
gnunet |
Subject: |
[taler-docs] branch master updated: nexus submit manual |
Date: |
Tue, 07 Nov 2023 18:51:05 +0100 |
This is an automated email from the git hooks/post-receive script.
ms pushed a commit to branch master
in repository docs.
The following commit(s) were added to refs/heads/master by this push:
new c97d8db8 nexus submit manual
c97d8db8 is described below
commit c97d8db8e7feefad58a0f943e4cde5bc018c5d12
Author: MS <ms@taler.net>
AuthorDate: Tue Nov 7 18:50:57 2023 +0100
nexus submit manual
---
libeufin/nexus-manual.rst | 113 ++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 113 insertions(+)
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.
--
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [taler-docs] branch master updated: nexus submit manual,
gnunet <=