nexus-manual.rst (15691B)
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 .. contents:: Table of Contents 41 :local: 42 43 44 Installing Nexus 45 ================ 46 47 The following section was tested on an *OpenJDK 17* environment. 48 49 50 Installing the libeufin-nexus binary packages on Debian 51 ------------------------------------------------------- 52 53 .. include:: ../frags/installing-debian.rst 54 55 .. include:: ../frags/apt-install-libeufin-nexus.rst 56 57 58 Installing the libeufin-nexus binary packages on Ubuntu 59 ------------------------------------------------------- 60 61 .. include:: ../frags/installing-ubuntu.rst 62 63 .. include:: ../frags/apt-install-libeufin-nexus.rst 64 65 66 Building from source 67 -------------------- 68 69 Nexus belongs to the LibEuFin project, and can be downloaded via Git: 70 71 .. code-block:: console 72 73 $ git clone git://git.taler.net/libeufin 74 75 Note that Kotlin and Gradle should already work on the host system. 76 77 Navigate into the *libeufin* local repository, and from top-level run: 78 79 .. code-block:: console 80 81 $ ./bootstrap 82 $ ./configure --prefix=$PREFIX 83 $ make install 84 85 If the previous steps succeeded, the ``libeufin-nexus`` command should 86 be found in the $PATH. 87 88 .. _ebics-setup: 89 90 Database setup 91 ============== 92 93 The configuration file must include a connection string that 94 tells Nexus how it should connect to the database. The default 95 is: 96 97 .. code-block:: ini 98 99 [libeufin-nexusdb-postgres] 100 config = postgres:///libeufin 101 102 You must make sure that this database exists and is accessible to the user 103 running Nexus before continuing. Then, the Nexus database schema must be 104 created (or updated) to the current Nexus version using the following command: 105 106 .. code-block:: console 107 108 $ libeufin-nexus-dbinit -c "$CONFIG_FILE" 109 110 where ``$CONFIG_FILE`` is again the path to a configuration that contains at 111 least the above ``[libeufin-nexusdb-postgres]`` section. 112 113 Setting up the EBICS subscriber 114 =============================== 115 116 .. include:: ../frags/nexus-ebics-setup.rst 117 118 .. _sending-payments: 119 120 Sending payments 121 ================ 122 123 Sending payments must follow a successful `EBICS subscriber setup 124 <ebics-setup>`_, where the bank obtained the subscriber keys, and the 125 subscriber accepted the bank keys. Furthermore, the database has to 126 be set up. Right now, some other process must queue payments to be 127 submitted to the database, so this section only discusses how such 128 queued payments will be executed. 129 130 The responsible subcommand for sending payments is ``ebics-submit``, and its 131 configuration is a **superset** of core-config_. On top of that, it expects 132 the database connection string and *optionally* a frequency at which it will 133 check for submittable payments in the database. 134 135 The frequency **may** be specified as 136 137 .. code-block:: ini 138 139 [nexus-submit] 140 FREQUENCY = 5m 141 142 The supported time units are ``s`` (seconds), ``m`` (minutes), ``h`` (hours). 143 144 145 For testing 146 ----------- 147 148 The ``ebics-submit`` subcommand is **not** suitable to send arbitrary 149 payments, but rather to submit initiated payments that are already queued for 150 submission in the Nexus database. 151 152 Such queued payments may originate from bounces of incoming payments with a 153 subject that would be invalid for a Taler withdrawal, or from a Taler exchange 154 that needs to send a payment to a merchant. 155 156 For testing purposes it is possible to manually initiate a payment using the 157 ``initiate-payment`` subcommand. 158 The following invocation pays 1 CHF to the CH987654321 with an "Hello, Nexus!" 159 subject: 160 161 .. code-block:: console 162 163 $ libeufin-nexus initiate-payment -c "$CONFIG_FILE" --subject "Hello, Nexus!" "payto://iban/CH987654321?receiver-name=Name&amount=CHF:1" 164 165 ``$CONFIG_FILE`` is the path to Nexus' configuration file and it does not need 166 the FREQUENCY value. If the previous command worked, now the database should 167 contain a new row in the ``initiated_outgoing_transactions`` table, with an 168 ``unsubmitted`` submission state. 169 170 The following command would now pick such an unsubmitted initiated payment and 171 send it to the bank. 172 173 174 .. code-block:: console 175 176 $ libeufin-nexus ebics-submit -c "$CONFIG_FILE" --transient 177 178 The ``--transient`` flag instructs the software to perform only one pass on 179 the database, submit what is submittable, and return. 180 181 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. 182 183 For production 184 -------------- 185 186 The ``ebics-submit`` subcommand can run in fixed frequency, or transient mode. 187 188 The fixed frequency mode causes the command to check the database every time the 189 frequency period expires. To activate this mode, and -- for example -- set a frequency 190 of five minutes, set the configuration value ``FREQUENCY`` to ``5m``. Assuming that 191 ``FREQUENCY`` is set as described above, the following invocation would 192 make ``ebics-submit`` check the database every five minutes, and submit any initiated 193 payment according to their submission state. 194 195 .. code-block:: console 196 197 $ libeufin-nexus ebics-submit -c "$CONFIG_FILE" 198 199 Transient mode causes ``ebics-submit`` to check the database only once, submit any 200 initiated payment according to their submission state, and return. 201 202 .. code-block:: console 203 204 $ libeufin-nexus ebics-submit -c "$CONFIG_FILE" 205 206 207 .. _receive-transaction-data: 208 209 Downloading payment records 210 =========================== 211 212 Downloading payments must follow a successful `EBICS subscriber setup 213 <ebics-setup>`_, where the bank obtained the subscriber keys, and the 214 subscriber accepted the bank keys. Furthermore, the database has to 215 be set up. 216 217 The responsible subcommand for fetching and registering payments is 218 ``ebics-fetch``, and its configuration is a **superset** of core-config_. On 219 top of that, it expects the database connection string and *optionally* a 220 frequency and a checkpoint time of day. 221 222 For the best user experience, new transactions should be registered as soon as 223 they are booked. This is especially important for instant transactions, which 224 reach final status in ~10 seconds. On the other hand, EBICS document fetches 225 are slow and expensive and should not be performed more than necessary. 226 227 ``ebics-fetch`` will run a periodical fetch of pending documents (documents 228 that have never been fetched before). If the bank server supports it, it will 229 also listen to real-time document availability notifications and fetch 230 documents as soon as they are announced. This enables instant registration of 231 instant transactions. If your bank server does not support real-time 232 notifications, it is recommended that you fetch more often; otherwise, you can 233 reduce the fetch frequency. 234 235 Only fetching pending documents is not always reliable, if other EBICS clients 236 use the same connection settings as ``libeufin-nexus``, they can consume documents before they are ingested. In case of bank downtime, the status of 237 documents can be lost. This is why ``ebics-fetch`` will run a checkpoint every 238 day to download all documents generated since the last checkpoint. 239 240 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. 241 242 The frequency **may** be specified as 243 244 .. code-block:: ini 245 246 [nexus-fetch] 247 FREQUENCY = 5m 248 249 The supported time units are ``s`` (seconds), ``m`` (minutes), ``h`` (hours). 250 251 The checkpoint time of day **may** be specified as 252 253 .. code-block:: ini 254 255 [nexus-fetch] 256 CHECKPOINT_TIME_OF_DAY = 19:00 257 258 Assuming that ``$CONFIG_FILE`` contains all required options, the following 259 command would download any unseen EBICS files: 260 261 .. code-block:: console 262 263 $ libeufin-nexus ebics-fetch -c "$CONFIG_FILE" --transient 264 265 The ``ebics-fetch`` subcommand will always cause libeufin-nexus to download 266 then parse EBICS files and register their content statements into its local 267 database. 268 269 The ``--transient`` flag makes the command download and import EBICS files only 270 once and return immediately afterwards. Without the flag, Nexus 271 will download at the frequency specified in the configuration or when it receive real time notifications. 272 273 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. 274 275 Bounce fee 276 ---------- 277 278 When a transaction is malformed, she is bounced back, the amount received is transferred back to the sender. 279 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. 280 281 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: 282 283 .. code-block:: ini 284 285 [nexus-fetch] 286 # LibEuFin Nexus can automatically deduce the transfer fees if they appears inside camt files 287 BOUNCE_DEDUCE_FEE = YES 288 # Or/and you can apply a fixed bounce fee 289 BOUNCE_FEE = CURRENCY:0.1 290 291 Account restriction 292 ------------------- 293 294 If you configured an exchange with ``credit_restrictions``, you should configure LibEuFin Nexus to bounce transactions coming from restricted accounts automatically: 295 296 .. code-block:: ini 297 298 [nexus-fetch] 299 # Use the same regex used during exchange configuration 300 RESTRICTION_PAYTO_REGEX = payto://iban/CH.* 301 302 For Testing 303 ----------- 304 305 If the bank account history has transactions that are useful for testing, it is 306 possible to re-download them via the ``--pinned-start`` argument. 307 308 The following command redownloads transactions *from* the pinned start until 309 the present: 310 311 .. code-block:: console 312 313 $ libeufin-nexus ebics-fetch -c "$CONFIG_FILE" --checkpoint --pinned-start 2023-11-01 314 315 .. note:: 316 317 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. 318 319 Be careful when resetting the database: resetting the wrong database might cause DATA LOSS! 320 321 Use the ``IGNORE_BOUNCES_BEFORE`` configuration to prevent malformed transactions from being bounced a second time when they are registered again. 322 323 Manual balance adjustement 324 ========================== 325 326 As LibEuFin Nexus is a Taler-specific EBICS client, it ignores non-payment 327 transactions. This means that certain debits from your banks for fees or taxes 328 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. 329 330 To fix this, you must periodically send administrative balance adjustment 331 transfers conaining "ADMIN BALANCE ADJUST" in their subject. 332 333 Manual submission acknowledgement 334 ================================= 335 336 By default LibEuFin Nexus automatically start submitting all initiated payments. You can enforce manual submission acknowledgement by changing your config: 337 338 .. code-block:: ini 339 340 [nexus-submit] 341 MANUAL_ACK = YES 342 343 To list pending transactions run: 344 345 .. code-block:: console 346 347 $ libeufin-nexus list initiated -c "$CONFIG_FILE" --awaiting-ack 348 349 To enable the submission of some transactions run: 350 351 .. code-block:: console 352 353 $ libeufin-nexus manual ack -c "$CONFIG_FILE" $IDS 354 355 Manual EBICS import & export 356 ============================ 357 358 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. 359 360 Sending payments 361 ---------------- 362 363 To obtain PAIN files for pending initiated outgoing transactions in a ``payments.zip`` file, you can run : 364 365 .. code-block:: console 366 367 $ libeufin-nexus manual export -c "$CONFIG_FILE" payments.zip 368 369 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. 370 371 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. 372 373 If the batch has been uploaded successfully, you can run this command: 374 375 .. code-block:: console 376 377 $ libeufin-nexus manual status -c "$CONFIG_FILE" batch $BATCH_ID pending 378 379 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: 380 381 .. code-block:: console 382 383 $ libeufin-nexus manual status -c "$CONFIG_FILE" batch $BATCH_ID transient_failure "In maintenance until Wednesday morning" 384 385 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: 386 387 .. code-block:: console 388 389 $ libeufin-nexus manual status -c "$CONFIG_FILE" batch $BATCH_ID permanent_failure "Unuspported transaction kind" 390 391 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: 392 393 .. code-block:: console 394 395 $ libeufin-nexus manual status -c "$CONFIG_FILE" batch $BATCH_ID pending 396 $ libeufin-nexus manual status -c "$CONFIG_FILE" tx $TX_ID permanent_failure "Malformed IBAN" 397 398 Successful transactions should be announced in CAMT files, so you shouldn't have to mark them as successful manually, but you still can with: 399 400 .. code-block:: console 401 402 $ libeufin-nexus manual status -c "$CONFIG_FILE" tx $TX_ID success 403 404 Import payment record 405 --------------------- 406 407 To import CAMT files, you can run: 408 409 .. code-block:: console 410 411 $ libeufin-nexus manual import -c "$CONFIG_FILE" camt53.xml 412 413 Files will be processed as if they had been downloaded using the EBICS protocol.