1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
|
.. target audience: operator, developer
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.
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.
Installing Nexus
================
The following section was tested on an *OpenJDK 17* environment.
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/ebics-setup.rst
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 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.
The connection string is specified as
.. code-block:: ini
[nexus-postgres]
config = postgres:///nexus
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
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.
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.
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
``$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.
.. code-block:: console
$ libeufin-nexus ebics-submit -c $config_fixed_frequency
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
Downloading 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.
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.
.. code-block:: ini
[nexus-postgres]
config = postgres:///nexus
[nexus-fetch]
# Optional, but usefull against data loss.
statement_log_directory = $LIBEUFIN_DATA_HOME/downloads
Assuming that ``$config_file`` contains any required option, the following command
would download any unseen notifications (as camt.054 files).
.. code-block:: console
$ libeufin-nexus ebics-fetch -c $config_file --transient
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.
To activate periodic downloads, add the following setting to the ``nexus-fetch``
configuration section in ``$config_file``:
.. code-block:: ini
[nexus-fetch]
frequency = 5m
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.
.. code-block:: console
$ libeufin-nexus ebics-fetch -c $config_file
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.
.. 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):
.. code-block:: console
$ libeufin-nexus ebics-fetch -c $config_file --pinned-start 2023-06-01
.. note::
The command redownloads transactions *from* the pinned start until the present.
|
