commit d9d084be23b484dac9da7940c55712028343fd46
parent 86eeb76d05c65e7ee0f8eccfc3221920d19967a9
Author: MS <ms@taler.net>
Date: Fri, 7 Jul 2023 09:05:03 +0200
EBICS 3 tutorial draft.
Diffstat:
1 file changed, 111 insertions(+), 0 deletions(-)
diff --git a/libeufin/ebics3-test-tutorial.rst b/libeufin/ebics3-test-tutorial.rst
@@ -0,0 +1,111 @@
+EBICS 3.0 with PostFinance
+##########################
+
+In this tutorial, LibEuFin Nexus communicates with the PostFinance
+test platform via EBICS 3.0. The reader is required to have one account
+at the `PostFinance test platform <https://isotest.postfinance.ch>`_,
+and a Docker environment.
+
+This EBICS 3.0 communication involves the following three operations:
+
+* Key exchange: Nexus gives the customer keys to the bank, and then downloads the bank keys.
+* Uploading of a payment instruction: the customer sends money to another fictional IBAN.
+* Downloading of banking records: the customer gets their banking activity where the previous outgoing payment should appear.
+
+Setting up the test platform
+----------------------------
+Login and navigate to the $MEANT section and set all the
+values like shown in the following image.
+
+.. Pictorial example..
+
+.. More pictorial examples here..
+
+Setting up the local Docker
+---------------------------
+
+Clone the following repository:
+
+.. code-block:: shell-session
+
+ git://git.taler.net/deployment
+
+Navigate in the following directory
+
+.. code-block:: shell-session
+
+ deployment/nlnet/task3
+
+And build the Docker image with the following command:
+
+.. code-block:: shell-session
+
+ docker build -t pofi .
+
+If the previous steps succeeded, the *pofi* image is ready to be run.
+Although the test runner guides the user via interactive instructions,
+it's advised to read the `Testing description` section.
+
+The test runner needs the following two values: EBICS user ID and EBICS
+partner ID. Please, find them in the following page:
+
+.. FIXME: screenshot here.
+
+.. code-block:: shell-session
+
+ docker run -it pofi $EBICS_USER_ID $EBICS_PARTNER_ID
+
+
+Testing description
+-------------------
+
+The first operation is the key exchange with the bank. EBICS has
+encrypted and signed communication from both client and server; for
+this reason the client will send its keys to the bank, and viceversa.
+
+Note: after the client sends its keys to the bank, those should
+be confirmed via another channel; usually that's done via a ordinary
+paper letter but in this case the test platform allows such confirmation
+via the Web interface. Therefore, after having uploaded the client
+keys to the bank, the test runner pauses the execution to let the
+user confirm the keys via the Web interface.
+
+After the key exchange, the test runner continues by uploading one
+payment instruction. The payment instruction is a ``pain.001`` document
+that complies with the ISO20022 specification and EBICS is responsible
+to transport the pain.001 from the client to the bank.
+
+The payment instruction causes one outgoing payment from the user
+test platform account to another fictional IBAN and has a random subject.
+A chance to specify a custom subject is also offered by the test runner.
+
+After the upload to the bank, the execution pauses to let the user
+check whether the test platform has received the payment instruction.
+The following screenshot shows where to look for such check:
+
+.. FIXME: screenshot here
+
+At this point, the upload operation ended and the execution can proceed
+to test the download. The download tries to get one ``camt.054`` (as well
+ISO20022) document from the bank; this document is expected to account
+for the previous outgoing payment that was created via the pain.001. As
+in the pain.001 case, EBICS is responsible to transport the camt.054 from
+the bank to the client.
+
+The download operation logs its activity to the screen, and if the execution
+is correct, the user should check for the payment subject that was initially
+specified in the pain.001 document.
+
+Please, look for the following line:
+
+.. note::
+
+ Replace $TIME, $PAYMENT_SUBJECT and $MSG_ID with the particular case.
+
+.. code-block:: shell-session
+
+ $TIME [main] DEBUG tech.libeufin.nexus - Camt NOTIFICATION '$MSG_ID' has new payments:
+ - $PAYMENT_SUBJECT
+
+If $PAYMENT_SUBJECT equals the initial payment subject from the pain.001,
+then the download operation succeeded.
