summaryrefslogtreecommitdiff
path: root/libeufin/nexus-tutorial.rst
blob: e919ed8c7992155db6b13dbbe52ca3d4284fe829 (plain)
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
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
Nexus How-To
############

.. contents:: Table of Contents

Nexus is a Web service that provides a JSON abstraction layer to
access bank accounts.  It is **not** itself a bank, but a translator
between JSON requests and more structured banking protocols (like
EBICS, for example), that are offered by actual banks.

This document explains how to set up Nexus to access a bank account
via the EBICS protocol.  In order to follow all the steps below, the
reader should already have one EBICS subscriber activated at their bank.

Obtain Nexus
============
Nexus belongs to the LibEuFin project, and can be downloaded via Git:

.. code-block:: console

  $ git clone git://git.taler.net/libeufin

Note that Kotlin+Gradle should already work on the host system.

Install Nexus
=============
Navigate into the `libeufin` local repository, and from top-level run:

.. code-block:: console

  $ ./gradlew -Pprefix=$PREFIX nexus:installToPrefix
  $ ./gradlew -Pprefix=$PREFIX cli:installToPrefix

In case of success, the two following commands should be found:

.. code-block:: console

  $ which libeufin-nexus
  $ which libeufin-cli

Connect Nexus with a EBICS account
==================================

Use the following command to *(1) run the nexus service*:

.. code-block:: console

  $ libeufin-nexus

After the startup, Nexus should have created a ``.sqlite3`` file in
its current working directory.  Feel free to use the ``--with-db`` option
to change the database name and path.  In future releases, the support
for PostgreSQL will be provided.

At this point a *(2) superuser account needs to be activated
into the system*:

.. code-block:: console

  $ libeufin-nexus superuser foo # Will interactively ask for password

For simplicity, we'll enable the superuser to access the bank account
via the EBICS protocol, but a API to create less privileged users is
offered as well.

Nexus needs now to associate the user to a EBICS subscriber that was
activated on the bank.  In the Nexus terminology, this is called *(3)
creating a EBICS connection*.

.. note::

  The command line interface needs the following three values
  to be defined in the environment: ``NEXUS_BASE_URL``, ``NEXUS_USERNAME``,
  and ``NEXUS_PASSWORD``.  In this example, ``NEXUS_USERNAME`` should be
  set to ``foo``, and ``NEXUS_PASSWORD`` to the value given for its password
  in step (2).

.. code-block:: console

  $ libeufin-cli \
      connections \
        new-ebics-connection \
          --ebics-url $EBICS_BASE_URL \
          --host-id $EBICS_HOST_ID \
          --partner-id $EBICS_PARTNER_ID \
          --ebics-user-id $EBICS_USER_ID \
          $CONNECTION_NAME

If the step above executed correctly, Nexus created all the cryptographic
material that is needed on the client side; in this EBICS example, it created
the signature and identification keys.  It is therefore advisable to *(4) make
a backup copy* of such keys.

.. code-block:: console

  $ libeufin-cli \
      connections \
        export-backup \
          --passphrase $SECRET \
          --outputfile $BACKUP_FILE \
          $CONNECTION_NAME

At this point, Nexus must communicate all the details to the bank.  Therefore,
it will *(5) synchronize the connection*.  In this EBICS example, Nexus will send
the *INI* and *HIA* messages to the bank.

.. code-block:: console

  $ libeufin-cli \
      connections \
        sync \
          $CONNECTION_NAME

Once the connection is synchronized, Nexus needs to import locally the data
corresponding to the bank accounts offered by the bank connection just made.
The command below *(6) downloads the list of the bank accounts offered by the*
``$CONNECTION_NAME``.

.. code-block:: console

  $ libeufin-cli \
      connections \
        download-bank-accounts \
          $CONNECTION_NAME

It is now possible to *(7) list the accounts offered by the connection*.

.. code-block:: console

  $ libeufin-cli \
      connections \
        list-offered-bank-accounts \
          $CONNECTION_NAME

Nexus now needs an explicit *(8) import of the accounts it needs to manage*.
This step is needed to let the user pick a custom name for such accounts.

.. code-block:: console

  $ libeufin-cli
      connections \
        import-bank-account \
          --offered-account-id $ACCOUNT_NATIVE_NAME \
          --nexus-bank-account-id $CUSTOM_RENAMING_FOR_ACCOUNT \
          $CONNECTION_NAME

Once a Nexus user imported a bank account (``$CUSTOM_RENAMING_FOR_ACCOUNT``)
under a certain connection (``$CONNECTION_NAME``), it is possible
to accomplish the usual operations for any bank account: asking for the
list of transactions, and making a payment.

Request history of transactions
===============================

..
  FIXME: explain why requesting the history
  goes through these two-phases.

It is first needed to tell Nexus to download the latest news
from the bank, and then ask it again to return the results.

This command asks Nexus to *download the latest bank statements*:

.. code-block:: console

  $ libeufin-cli \
      accounts \
        fetch-transactions \
          $CUSTOM_RENAMING_FOR_ACCOUNT

Once Nexus stored all the information in the database, the
client can ask to actually **see** the transactions:

.. code-block:: console

  $ libeufin-cli
      accounts \
        transactions \
          $CUSTOM_RENAMING_FOR_ACCOUNT

Make a payment
==============

..
  FIXME: explain why payments go through these two-phases.

Payments pass through two phases: preparation and submission.

The following command prepares a payment:

.. code-block:: console

  $ libeufin-cli \
      accounts \
        prepare-payment \
          --credit-iban $IBAN_TO_SEND_MONEY_TO \
          --credit-bic $BIC_TO_SEND_MONEY_TO \
          --credit-name $LEGAL_ENTITY_RECEIVING_THE_PAYMENT \
          --payment-amount $AMOUNT \
          --payment-subject $SUBJECT \
          $CUSTOM_RENAMING_FOR_ACCOUNT

Note: the ``$AMOUNT`` value needs the format ``X.Y:CURRENCY``; for example
``10:EUR``, or ``1.01:EUR``.

The previous command should return a value (``$UUID``) that uniquely
identifies the prepared payment in the Nexus system.  It'll be needed
in the next step, to **send the payment instructions to the bank**:

.. code-block:: console

  $ libeufin-cli \
      accounts \
        submit-payment \
          --payment-uuid $UUID \
          $CUSTOM_RENAMING_FOR_ACCOUNT


Restore the backup
==================

The following command shows how to restore all the details
associated with one bank connection subscription.  For EBICS,
this means that the INI and HIA secret keys will be restored
for the requesting user.

.. code-block:: console

  $ libeufin-cli \
      connection \
        restore-backup \
          --passphrase $SECRET \
          --outputfile $BACKUP_FILE \
          $CONNECTION_NAME

Creating a Taler facade
=======================

Facades are additional abstraction layers that can serve
specific purposes.  For example, one application might need
a filtered version of the transaction history, or it might
want to refuse payments that do not conform to certain rules.

At this moment, only the *Taler facade type* is implemented
in the Nexus, and the command below will show how to instantiate
one under an existing bank account.

.. code-block:: console

  $ libeufin-cli \
      taler-facade \
        new-facade \
          --facade-name $FACADE_NAME \
          $CONNECTION_NAME \
          $CUSTOM_RENAMING_FOR_ACCOUNT

At this point, the additional *taler-wire-gateway* (link here) API
becomes offered by the Nexus.  The purpose is to let a Taler exchange
to rely on Nexus to manage its bank account.