nexus-manual.rst (15666B)
1 .. 2 This file is part of GNU TALER. 3 Copyright (C) 2014-2025 Taler Systems SA 4 5 TALER is free software; you can redistribute it and/or modify it under the 6 terms of the GNU Affero General Public License as published by the Free Software 7 Foundation; either version 2.1, or (at your option) any later version. 8 9 TALER is distributed in the hope that it will be useful, but WITHOUT ANY 10 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 11 A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. 12 13 You should have received a copy of the GNU Affero General Public License along with 14 TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> 15 16 @author Antoine d'Aligny 17 @author Florian Dold 18 @author Marcello Stanisci 19 @author Christian Grothoff 20 21 .. target audience: operator, developer 22 23 .. _libeufin-nexus: 24 25 Nexus Manual 26 ############ 27 28 LibEuFin Nexus is an EBICS facilitator. It offers a command line interface to 29 setup EBICS access, download banking records, and submit payments. LibEuFin Nexus is not a generic EBICS client but a Taler specific one. 30 31 Today, the LibEuFin implementation supports EBICS 3.0 and has been 32 tested with Postfinance (CHF), GLS (EUR), Maerki Baumann (CHF) and Valiant (CHF). Please note 33 that banks tend to have their own dialects of finance messages and thus other 34 retail banks may or may not work. Contact us if you need support for another 35 bank or core banking protocol. 36 37 In this manual, we explain how to setup an EBICS subscriber. We assume that 38 the bank has already granted EBICS access to the subscriber. 39 40 Installing Nexus 41 ================ 42 43 The following section was tested on an *OpenJDK 17* environment. 44 45 46 Installing the libeufin-nexus binary packages on Debian 47 ------------------------------------------------------- 48 49 .. include:: ../frags/installing-debian.rst 50 51 .. include:: ../frags/apt-install-libeufin-nexus.rst 52 53 54 Installing the libeufin-nexus binary packages on Ubuntu 55 ------------------------------------------------------- 56 57 .. include:: ../frags/installing-ubuntu.rst 58 59 .. include:: ../frags/apt-install-libeufin-nexus.rst 60 61 62 Building from source 63 -------------------- 64 65 Nexus belongs to the LibEuFin project, and can be downloaded via Git: 66 67 .. code-block:: console 68 69 $ git clone git://git.taler.net/libeufin 70 71 Note that Kotlin and Gradle should already work on the host system. 72 73 Navigate into the *libeufin* local repository, and from top-level run: 74 75 .. code-block:: console 76 77 $ ./bootstrap 78 $ ./configure --prefix=$PREFIX 79 $ make install 80 81 If the previous steps succeeded, the ``libeufin-nexus`` command should 82 be found in the $PATH. 83 84 .. _ebics-setup: 85 86 Database setup 87 ============== 88 89 The configuration file must include a connection string that 90 tells Nexus how it should connect to the database. The default 91 is: 92 93 .. code-block:: ini 94 95 [libeufin-nexusdb-postgres] 96 config = postgres:///libeufin 97 98 You must make sure that this database exists and is accessible to the user 99 running Nexus before continuing. Then, the Nexus database schema must be 100 created (or updated) to the current Nexus version using the following command: 101 102 .. code-block:: console 103 104 $ libeufin-nexus-dbinit -c "$CONFIG_FILE" 105 106 where ``$CONFIG_FILE`` is again the path to a configuration that contains at 107 least the above ``[libeufin-nexusdb-postgres]`` section. 108 109 Setting up the EBICS subscriber 110 =============================== 111 112 .. include:: ../frags/nexus-ebics-setup.rst 113 114 .. _sending-payments: 115 116 Sending payments 117 ================ 118 119 Sending payments must follow a successful `EBICS subscriber setup 120 <ebics-setup>`_, where the bank obtained the subscriber keys, and the 121 subscriber accepted the bank keys. Furthermore, the database has to 122 be set up. Right now, some other process must queue payments to be 123 submitted to the database, so this section only discusses how such 124 queued payments will be executed. 125 126 The responsible subcommand for sending payments is ``ebics-submit``, and its 127 configuration is a **superset** of :ref:`nexus-core-config`. On top of that, it expects 128 the database connection string and *optionally* a frequency at which it will 129 check for submittable payments in the database. 130 131 The frequency **may** be specified as 132 133 .. code-block:: ini 134 135 [nexus-submit] 136 FREQUENCY = 5m 137 138 The supported time units are ``s`` (seconds), ``m`` (minutes), ``h`` (hours). 139 140 141 For testing 142 ----------- 143 144 The ``ebics-submit`` subcommand is **not** suitable to send arbitrary 145 payments, but rather to submit initiated payments that are already queued for 146 submission in the Nexus database. 147 148 Such queued payments may originate from bounces of incoming payments with a 149 subject that would be invalid for a Taler withdrawal, or from a Taler exchange 150 that needs to send a payment to a merchant. 151 152 For testing purposes it is possible to manually initiate a payment using the 153 ``initiate-payment`` subcommand. 154 The following invocation pays 1 CHF to the CH987654321 with an "Hello, Nexus!" 155 subject: 156 157 .. code-block:: console 158 159 $ libeufin-nexus initiate-payment -c "$CONFIG_FILE" --subject "Hello, Nexus!" "payto://iban/CH987654321?receiver-name=Name&amount=CHF:1" 160 161 ``$CONFIG_FILE`` is the path to Nexus' configuration file and it does not need 162 the FREQUENCY value. If the previous command worked, now the database should 163 contain a new row in the ``initiated_outgoing_transactions`` table, with an 164 ``unsubmitted`` submission state. 165 166 The following command would now pick such an unsubmitted initiated payment and 167 send it to the bank. 168 169 170 .. code-block:: console 171 172 $ libeufin-nexus ebics-submit -c "$CONFIG_FILE" --transient 173 174 The ``--transient`` flag instructs the software to perform only one pass on 175 the database, submit what is submittable, and return. 176 177 The ``--debug-ebics $SAVEDIR`` flag will cause EBICS transactions steps and payloads to be stored in ``$SAVEDIR/$YYYY-MM-DD`` where ``$YYYY-MM-DD`` represents the date when the upload took place. This is mostly useful for debugging. 178 179 For production 180 -------------- 181 182 The ``ebics-submit`` subcommand can run in fixed frequency, or transient mode. 183 184 The fixed frequency mode causes the command to check the database every time the 185 frequency period expires. To activate this mode, and -- for example -- set a frequency 186 of five minutes, set the configuration value ``FREQUENCY`` to ``5m``. Assuming that 187 ``FREQUENCY`` is set as described above, the following invocation would 188 make ``ebics-submit`` check the database every five minutes, and submit any initiated 189 payment according to their submission state. 190 191 .. code-block:: console 192 193 $ libeufin-nexus ebics-submit -c "$CONFIG_FILE" 194 195 Transient mode causes ``ebics-submit`` to check the database only once, submit any 196 initiated payment according to their submission state, and return. 197 198 .. code-block:: console 199 200 $ libeufin-nexus ebics-submit -c "$CONFIG_FILE" 201 202 203 .. _receive-transaction-data: 204 205 Downloading payment records 206 =========================== 207 208 Downloading payments must follow a successful `EBICS subscriber setup 209 <ebics-setup>`_, where the bank obtained the subscriber keys, and the 210 subscriber accepted the bank keys. Furthermore, the database has to 211 be set up. 212 213 The responsible subcommand for fetching and registering payments is 214 ``ebics-fetch``, and its configuration is a **superset** of nexus-core-config_. On 215 top of that, it expects the database connection string and *optionally* a 216 frequency and a checkpoint time of day. 217 218 For the best user experience, new transactions should be registered as soon as 219 they are booked. This is especially important for instant transactions, which 220 reach final status in ~10 seconds. On the other hand, EBICS document fetches 221 are slow and expensive and should not be performed more than necessary. 222 223 ``ebics-fetch`` will run a periodical fetch of pending documents (documents 224 that have never been fetched before). If the bank server supports it, it will 225 also listen to real-time document availability notifications and fetch 226 documents as soon as they are announced. This enables instant registration of 227 instant transactions. If your bank server does not support real-time 228 notifications, it is recommended that you fetch more often; otherwise, you can 229 reduce the fetch frequency. 230 231 Only fetching pending documents is not always reliable, if other EBICS clients 232 use the same connection settings as ``libeufin-nexus``, they can consume documents before they are ingested. In case of bank downtime, the status of 233 documents can be lost. This is why ``ebics-fetch`` will run a checkpoint every 234 day to download all documents generated since the last checkpoint. 235 236 If the bank supports real-time notifications, you can expect transactions to be registered as soon as they are booked: ~10s for instant transactions and 24 to 72h for other transactions. Otherwise, expect a latency corresponding to the fetch frequency for instant transactions. Thanks to checkpointing, latency should not exceed one day. 237 238 The frequency **may** be specified as 239 240 .. code-block:: ini 241 242 [nexus-fetch] 243 FREQUENCY = 5m 244 245 The supported time units are ``s`` (seconds), ``m`` (minutes), ``h`` (hours). 246 247 The checkpoint time of day **may** be specified as 248 249 .. code-block:: ini 250 251 [nexus-fetch] 252 CHECKPOINT_TIME_OF_DAY = 19:00 253 254 Assuming that ``$CONFIG_FILE`` contains all required options, the following 255 command would download any unseen EBICS files: 256 257 .. code-block:: console 258 259 $ libeufin-nexus ebics-fetch -c "$CONFIG_FILE" --transient 260 261 The ``ebics-fetch`` subcommand will always cause libeufin-nexus to download 262 then parse EBICS files and register their content statements into its local 263 database. 264 265 The ``--transient`` flag makes the command download and import EBICS files only 266 once and return immediately afterwards. Without the flag, Nexus 267 will download at the frequency specified in the configuration or when it receive real time notifications. 268 269 The ``--debug-ebics $SAVEDIR`` flag will cause EBICS transactions steps and payloads to be stored in ``$SAVEDIR/$YYYY-MM-DD`` where ``$YYYY-MM-DD`` represents the date when the download took place. This is mostly useful for debugging. 270 271 Bounce fee 272 ---------- 273 274 When a transaction is malformed, she is bounced back, the amount received is transferred back to the sender. 275 First time users often make mistakes when sending a transaction manually, so you can expect frequent bounces. It's important that this process is user-friendly, which is why bounces are automatic. 276 277 However, bounces can be costly if your bank charges you transfer fees. Here are a few parameters you can adjust to get around this problem, but bear in mind that it's often better for business to bear this cost: 278 279 .. code-block:: ini 280 281 [nexus-fetch] 282 # LibEuFin Nexus can automatically deduce the transfer fees if they appears inside camt files 283 BOUNCE_DEDUCE_FEE = YES 284 # Or/and you can apply a fixed bounce fee 285 BOUNCE_FEE = CURRENCY:0.1 286 287 Account restriction 288 ------------------- 289 290 If you configured an exchange with ``credit_restrictions``, you should configure LibEuFin Nexus to bounce transactions coming from restricted accounts automatically: 291 292 .. code-block:: ini 293 294 [nexus-fetch] 295 # Use the same regex used during exchange configuration 296 RESTRICTION_PAYTO_REGEX = payto://iban/CH.* 297 298 For Testing 299 ----------- 300 301 If the bank account history has transactions that are useful for testing, it is 302 possible to re-download them via the ``--pinned-start`` argument. 303 304 The following command redownloads transactions *from* the pinned start until 305 the present: 306 307 .. code-block:: console 308 309 $ libeufin-nexus ebics-fetch -c "$CONFIG_FILE" --checkpoint --pinned-start 2023-11-01 310 311 .. note:: 312 313 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 registered. 314 315 Be careful when resetting the database: resetting the wrong database might cause DATA LOSS! 316 317 Use the ``IGNORE_BOUNCES_BEFORE`` configuration to prevent malformed transactions from being bounced a second time when they are registered again. 318 319 Manual balance adjustement 320 ========================== 321 322 As LibEuFin Nexus is a Taler-specific EBICS client, it ignores non-payment 323 transactions. This means that certain debits from your banks for fees or taxes 324 can be ignored. This imply that the actual balance of your bank account may deviate from that expected by Taler Exchange, leading to Exchange bankruptcy. 325 326 To fix this, you must periodically send administrative balance adjustment 327 transfers conaining "ADMIN BALANCE ADJUST" in their subject. 328 329 Manual submission acknowledgement 330 ================================= 331 332 By default LibEuFin Nexus automatically start submitting all initiated payments. You can enforce manual submission acknowledgement by changing your config: 333 334 .. code-block:: ini 335 336 [nexus-submit] 337 MANUAL_ACK = YES 338 339 To list pending transactions run: 340 341 .. code-block:: console 342 343 $ libeufin-nexus list initiated -c "$CONFIG_FILE" --awaiting-ack 344 345 To enable the submission of some transactions run: 346 347 .. code-block:: console 348 349 $ libeufin-nexus manual ack -c "$CONFIG_FILE" $IDS 350 351 Manual EBICS import & export 352 ============================ 353 354 If your bank does not support the EBICS protocol, but has an interface for importing and exporting ISO20022 files, you can run the deployment manually. 355 356 Sending payments 357 ---------------- 358 359 To obtain PAIN files for pending initiated outgoing transactions in a ``payments.zip`` file, you can run : 360 361 .. code-block:: console 362 363 $ libeufin-nexus manual export -c "$CONFIG_FILE" payments.zip 364 365 Each file in the ZIP file corresponds to a single batch of transactions. The command prints the details of each batch and their internal transactions. Files are generated as if they would be uploaded using the EBICS protocol. 366 367 As we have no way of knowing whether the upload was successful, you need to update the batch status manually. Until you tell ``libeufin-nexus`` that a batch has been uploaded successfully, it will re-export it next time. 368 369 If the batch has been uploaded successfully, you can run this command: 370 371 .. code-block:: console 372 373 $ libeufin-nexus manual status -c "$CONFIG_FILE" batch $BATCH_ID pending 374 375 Alternatively, if the error is transient, for example if the bank's user interface is under maintenance, you can set a temporary error accompanied by a message with: 376 377 .. code-block:: console 378 379 $ libeufin-nexus manual status -c "$CONFIG_FILE" batch $BATCH_ID transient_failure "In maintenance until Wednesday morning" 380 381 If the error is permanent, for example if the file is malformed and your bank will never accept it, you can define a permanent error with: 382 383 .. code-block:: console 384 385 $ libeufin-nexus manual status -c "$CONFIG_FILE" batch $BATCH_ID permanent_failure "Unuspported transaction kind" 386 387 It can also happen that a batch is partially successful, the batch is uploaded but some transactions failed, for example because a creditor's IBAN is incorrect. You can mark a batch as uploaded even though some transactions have failed with: 388 389 .. code-block:: console 390 391 $ libeufin-nexus manual status -c "$CONFIG_FILE" batch $BATCH_ID pending 392 $ libeufin-nexus manual status -c "$CONFIG_FILE" tx $TX_ID permanent_failure "Malformed IBAN" 393 394 Successful transactions should be announced in CAMT files, so you shouldn't have to mark them as successful manually, but you still can with: 395 396 .. code-block:: console 397 398 $ libeufin-nexus manual status -c "$CONFIG_FILE" tx $TX_ID success 399 400 Import payment record 401 --------------------- 402 403 To import CAMT files, you can run: 404 405 .. code-block:: console 406 407 $ libeufin-nexus manual import -c "$CONFIG_FILE" camt53.xml 408 409 Files will be processed as if they had been downloaded using the EBICS protocol.