commit e273c1795733bd5d736e634a55966aeaece4256d
parent 416bc151ac9fa4d5a2eab26231cdac3c5d2ef39a
Author: MS <ms@taler.net>
Date: Tue, 11 Jul 2023 14:08:09 +0200
EBICS 3 tutorial: proof reading
Diffstat:
1 file changed, 56 insertions(+), 27 deletions(-)
diff --git a/libeufin/ebics3-test-tutorial.rst b/libeufin/ebics3-test-tutorial.rst
@@ -1,13 +1,14 @@
EBICS 3.0 with PostFinance
##########################
-The tutorial shows how to run the Docker-based EBICS 3 test,
-where the user will be guided through the three main operations.
+This tutorial shows how LibEuFin and the PostFinance test platform
+communicate via EBICS 3. The EBICS communication is carried via a
+Docker image that guides the user through the main three EBICS operations.
The main EBICS 3 operations are the following:
-* 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.
+* Key exchange: Nexus uploads the customer keys to the bank, and then downloads the bank keys.
+* Uploading of a payment instruction: the customer sends a payment 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 at PostFinance
@@ -27,46 +28,74 @@ Even if the page doesn't welcome you in English, the two boxes in the
screenshot will still hold their position, so please look for box #1 to
set the language and for box #2 to get the page that offers to register.
-After a sucessful registration, the next two settings need to be given:
-(1) EBICS 3 and (2) the format of payment confirmations (more on this later).
+After a successful registration, an IBAN needs to be associated with
+the user just created. Likely after the first login, the following
+page should appear (if not, simply click on box #1). Click then on box #2.
-Note: setting EBICS 3 is not *explicit*, but it's a side effect of choosing
-one particular format for downloading the bank account records. The following
-screenshots show how. First, from the profile home page, click the navigation
-bar item highlighted in the following screenshot.
+.. image:: IBAN-setting-page.png
-.. image:: set-ISO-2019-0.png
+If the following page appears, please obtain a checksum-valid but fictitious
+Swiss IBAN and enter it as indicated by box #1 in the following screenshot, and
+then save it (box #2).
+
+.. _my-iban:
+
+.. image:: set-IBAN.png
+
+If the bank responds with a successful message, proceed with the following
+settings: EBICS 3, and the format of payment confirmations.
+
+.. note::
+
+ There is no "use EBICS 3" setting since EBICS 3 is a "side effect"
+ of choosing one particular ISO format for banking records.
+
+To use EBICS 3, click the navigation bar item highlighted in the
+following screenshot.
+.. note::
+
+ Such navigation bar is visible from any page in the test platform.
+
+.. image:: set-ISO-2019-0.png
The following page should appear, where the ISO format can be specified
as it is depicted in the following screenshot.
.. image:: set-ISO-2019-1.png
-Payment confirmations are ISO20022 documents that witness the outcome
-of outgoing payments. After sending 1 Swiss Franc to one arbitrary IBAN,
-the bank releases this document that contains all the payment details.
-In this test, we use this document to test the download capability of
-our EBICS 3 implementation. The specific name of such documents is
-``camt.054``, and the following screenshots show how to set them. From
-the profile home page, hover on box #1 and then click on box #2.
+After having saved the setting, proceed now to set the (sub-)format
+of payment confirmations. This setting instructs the bank to define
+particular XML nodes when it releases the payment confirmations. Even
+if each document is ISO20022, this step is essential because ISO20022
+has many optional fields and client and bank must agree on which fields
+appear in the documents.
+
+Hover on box #1 and then click on box #2.
.. image:: camt.054-style-0.png
-If the following page appear, please set everything as it is shown below:
+If the following page appears, please set everything as it is shown below:
+
+.. FIXME: now trying by NOT selecting the incoming confirmation.
+ Change it here if that works (screenshot taken already)!
.. image:: camt.054-style-1.png
.. _get-ebics-ids:
The last step is to retrieve the user's EBICS identifiers, namely the
-EBICS user and partner IDs. From the profile home page, hover on box #1
-and then click on box #2.
+EBICS user and partner IDs. Hover on box #1 and then click on box #2.
.. image:: get-EBICS-IDs-0.png
-After having navigated to the following page, finally the EBICS identifiers
-are shown in box #1. These values will be asked to launch the test runner.
+At the first access, the following page should appear. Simply enable
+EBICS and continue to the next step.
+
+.. image:: enable-EBICS.png
+
+After having obtained the following page, finally the EBICS identifiers
+are shown in box #1. These values are the parameters to the test runner.
**Note**: the terms 'customer' and 'partner' are used as **synonyms** in this
tutorial (and in the EBICS specifications too).
@@ -105,13 +134,13 @@ If the previous steps succeeded, the *pofi* image is ready to be run.
Although the test runner guides the user via live instructions,
it's advised to read the `Test details`_ section.
-The test runner needs the following two values: EBICS user ID and EBICS
-partner ID. The `previous section <get-ebics-ids_>`_ explains how
-to get them.
+The test runner needs the following three values: EBICS user ID, EBICS
+partner ID and IBAN. The `previous section <get-ebics-ids_>`_ explains how
+to get the EBICS IDs. The IBAN is the one entered `here <my-iban_>`_.
.. code-block:: shell-session
- docker run -it pofi $EBICS_USER_ID $EBICS_PARTNER_ID
+ docker run -it pofi $EBICS_USER_ID $EBICS_PARTNER_ID $MY_IBAN
Right after the start, the test runner needs the user intervention to
confirm the user keys at the bank side. For this reason, it will pause
