1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
|
EBICS 3.0 with PostFinance
##########################
This tutorial shows how LibEuFin and the PostFinance test platform
communicate via EBICS 3. LibEuFin acts as the client via the Nexus
component. To hide the configuration details to the user, all the
client activity is handled by a Docker image.
The main EBICS 3 operations that the client is expected to complete
are the following:
* Key exchange: the customer sends their keys to the bank, and then downloads the bank keys.
* Uploading a payment instruction: the customer sends a payment to another fictional IBAN.
* Downloading banking records: the customer downloads the banking records that confirm the previous outgoing payment.
Setting up the test platform at PostFinance
-------------------------------------------
Because the test is based on the PostFinance test platform, the first
requirement is to create one account `there <https://isotest.postfinance.ch>`_.
It is advised to set the language as English, as this tutorial is meant
for the international audience.
Set the language in the drop-down menu and navigate to the registration
section as it is shown below:
.. image:: set-english-and-register.png
Even if the above 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 successful registration, an IBAN needs to be associated with
the user just created. Likely after the first login, the following
page should appear. Click then on box #2.
.. note::
The navigation bar in the screenshot below is ubiquitous,
so click on box #1 if the depicted page did not show up automatically.
.. image:: no-accounts.png
If the following page appears, please obtain a checksum-valid but fictitious
Swiss IBAN and enter it as indicated by box #1 and then save it (box #2).
.. _my-iban:
.. image:: set-IBAN.png
If the bank responds with a successful message, the next step is to enable
EBICS 3 and set the format of the ISO20022 documents.
.. 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.
.. 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
After having saved the setting, proceed now to set the flavor
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 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. Hover on box #1 and then click on box #2.
.. image:: get-EBICS-IDs-0.png
At the first access, the following page should appear. Simply create
EBICS access 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. The test runner needs them. **Note**: the terms
'customer' and 'partner' are used as **synonyms** in this tutorial (and
in the EBICS specifications too).
.. image:: get-EBICS-IDs-1.png
Interestingly, box #2 contains the bank keys fingerprints. These are
important to check that the client, along the keying process, has obtained
the right bank keys. The test runner will pause the execution to let
the user check them.
Setting up the local Docker and run the test
--------------------------------------------
This section shows how to run the test and explains how to interact
with the test runner.
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.
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 $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
the execution until the user is done. The following screenshot shows
how to navigate to the page where the user has to intervene:
.. image:: get-EBICS-IDs-0.png
Once obtaining the page below, box #1 resets potential previous uploaded
keys (only required when running the test more than once), and box #2 confirms
the newly uploaded keys. Note: in production cases, such confirmation happens
via the traditional paper mail.
.. image:: set-EBICS-keys.png
After having confirmed the new keys, the execution can be resumed to
for the uploading and downloading operations.
Upload
======
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.
To this purpose, click on the following navigation item:
.. image:: check-payment-subject-0.png
the opened page should contain the following view:
.. image:: check-payment-subject-1.png
in this case, open the (archive) file whose timestamp corresponds to the
test execution and look for one XML file whose name contains "pain.001"
(likely, this XML file is named after the archive's name). If found,
the pain.001 file is expected to contain one node called ``Ustrd``: that
is the payment subject and must match the one that was specified right
before the upload. If they match, the upload succeeded and the execution
can be resumed for the `Download`_ operation.
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 payment subject that was initially specified in the pain.001
document must appear.
Please, look for the following line:
.. code-block:: shell-session
$TIME [main] DEBUG tech.libeufin.nexus - Camt NOTIFICATION '$MSG_ID' has new payments:
- $PAYMENT_SUBJECT
.. note::
Replace $TIME, $PAYMENT_SUBJECT and $MSG_ID with the particular case.
If $PAYMENT_SUBJECT equals the initial payment subject from the pain.001,
then the download operation succeeded.
|
