11.13. 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.
11.13.1. 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. 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:
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.
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).
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.
The following page should appear, where the ISO format can be specified as it is depicted in the following screenshot.
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.
If the following page appears, please set everything as it is shown below:
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.
At the first access, the following page should appear. Simply create EBICS access and continue to the next step.
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).
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.
11.13.2. 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:
git://git.taler.net/deployment
navigate in the following directory
deployment/nlnet/task3
and build the Docker image with the following command:
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 explains how to get the EBICS IDs. The IBAN is the one entered here.
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:
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.
After having confirmed the new keys, the execution can be resumed to for the uploading and downloading operations.
11.13.2.1. 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:
the opened page should contain the following view:
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.
11.13.2.2. 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:
$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.