commit eb2b942ad38765e62099d30577004a83cb3a0cbc
parent b3941efe803064a37dbbfad6d69378137eadfd20
Author: Antoine A <>
Date: Tue, 17 Dec 2024 13:20:40 +0100
libeufin: better nexus manual management doc
Diffstat:
1 file changed, 38 insertions(+), 7 deletions(-)
diff --git a/libeufin/nexus-manual.rst b/libeufin/nexus-manual.rst
@@ -295,30 +295,61 @@ the present:
Use the ``IGNORE_BOUNCES_BEFORE`` configuration to prevent malformed transactions from being bounced a second time when they are registered again.
Manual EBICS import & export
-----------------------------
+============================
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.
+Sending payments
+----------------
+
To obtain PAIN files for pending initiated outgoing transactions in a `payments.zip` file, you can run :
.. code-block:: console
$ libeufin-nexus manual export -c "$CONFIG_FILE" payments.zip
-You have to update the batch state status manually after the uplaod, you can run:
+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.
+
+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.
+
+If the batch has been uploaded successfully, you can run this command:
+
+.. code-block:: console
+
+ $ libeufin-nexus manual status -c "$CONFIG_FILE" batch $BATCH_ID pending
+
+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:
+
+.. code-block:: console
+
+ $ libeufin-nexus manual status -c "$CONFIG_FILE" batch $BATCH_ID transient_failure "In maintenance until Wednesday morning"
+
+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:
.. code-block:: console
- $ libeufin-nexus manual status -c "$CONFIG_FILE" batch $BATCH_ID success
+ $ libeufin-nexus manual status -c "$CONFIG_FILE" batch $BATCH_ID permanent_failure "Unuspported transaction kind"
-or
+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:
.. code-block:: console
- $ libeufin-nexus manual status -c "$CONFIG_FILE" batch $BATCH_ID permanent_failure "Unexpected error"
+ $ libeufin-nexus manual status -c "$CONFIG_FILE" batch $BATCH_ID pending
+ $ libeufin-nexus manual status -c "$CONFIG_FILE" tx $TX_ID permanent_failure "Malformed IBAN"
+
+Successful transactions should be announced in CAMT files, so you shouldn't have to mark them as successful manually, but you still can with:
+
+.. code-block:: console
+
+ $ libeufin-nexus manual status -c "$CONFIG_FILE" tx $TX_ID success
+
+Import payment record
+---------------------
To import CAMT files, you can run:
.. code-block:: console
- $ libeufin-nexus manual import -c "$CONFIG_FILE" camt53.xml
-\ No newline at end of file
+ $ libeufin-nexus manual import -c "$CONFIG_FILE" camt53.xml
+
+Files will be processed as if they had been downloaded using the EBICS protocol.
+\ No newline at end of file
