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 setup 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: ``$ 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:: shell $ ./gradlew -Pprefix=$PREFIX nexus:installToPrefix $ ./gradlew -Pprefix=$PREFIX cli:installToPrefix In case of success, the two following commands should be found: .. code-block:: shell $ which libeufin-nexus $ which libeufin-cli Connect Nexus with a EBICS account ================================== Use the following command to *(1) run the nexus service*: .. code-block:: shell $ 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:: shell $ 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 as well offered. 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 into 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:: shell 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:: shell 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:: shell 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:: shell libeufin-cli \ connections \ download-bank-accounts \ $CONNECTION_NAME It is now possible to *(7) list the accounts offered by the connection*. .. code-block:: shell 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:: shell 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:: shell 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:: shell 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:: shell 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:: shell 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:: shell 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:: shell 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.