XX 38: Demobanks protocol suppliers

10.38. XX 38: Demobanks protocol suppliers#

10.38.1. Summary#

This document models the association between financial data held in a LibEuFin demobank and the interface to let users access such financial data.

10.38.2. Motivation#

LibEuFin Sandbox offers multitenency banking by the means of ‘demobanks’. Each demobank offers access to financial data via several APIs. The objective is to model such APIs so that each operation impacts one and only one demobank.

10.38.3. Definitions#

Each API to access financial data at one demobank is offered by a resource called protocol supplier. Therefore protocol suppliers MAY be subject to all the CRUD operations

For each request that a protocol supplier serves, the demobank being impacted can be found in the following ways:

  1. In a value that belongs to the request.

  2. In a value that belongs to the protocol supplier’s state.

  3. Relying on the default demobank.

Note: the three elements are mutually exclusive, so as to reduce ambiguity and simplify the implementation.

10.38.4. Suppliers creation#

Suppliers can be static or dynamic.

10.38.4.1. Static#

This supplier never changes its state. Whether this type of supplier is associated or not with a particular demobank MUST be stated in the documentation.

10.38.4.1.1. Examples#

1. A JSON-based protocol that lets users access their bank accounts always under the ‘default’ demobank belongs to this category. It is therefore a ‘static protocol supplier’ with static demobank.

2. A XML-based protocol that lets users access their bank accounts in a demobank whose name appear in the URI is as well a ‘static protocol supplier’ with dynamic demobank.

Note: the upcoming (in version 0.9.3) JSON-based supplier that will let Nexus reach Sandbox accounts is planned as a ‘dynamic protocol supplier’ with dynamic demobank. That allows Taler demos to only speak JSON.

10.38.4.2. Dynamic#

This supplier has a name and its state CAN refer to one particular demobank. These suppliers need to be created first, in order to be used.

10.38.4.2.1. Examples#

1. A JSON-based protocol that lets users access their bank accounts under the demobank whose name is held in the supplier state belongs to this category. It is therefore a dynamic supplier with semi-dynamic demobank.

2. A XML-based protocol that lets user access their bank accounts under the demobank whose name is held both in the supplier state and in the URI is wrong. This supplier doesn’t respect this mutual exclusivity.

3. A XML-based protocol that lets user access their bank accounts always under the ‘default’ demobank belongs to this category. It is a dynamic supplier with static demobank.

10.38.5. Supplier reachability#

Each supplier must be available under its own URI.

10.38.6. Current protocol suppliers design#

10.38.6.1. Static X-LIBEUFIN-BANK with dynamic demobank#

The x-libeufin-bank protocol supplier is reachable under /demobanks/{demobankName}/access-api/. As the path suggests, it offers banking operations via the Core Bank API. It is static in the sense that it’s not possible to assign a name to one particular x-libeufin-bank protocol supplier. On the other hand, the demobank is dynamic because can be specified along the path in the demobankName placeholder.

10.38.6.2. Dynamic EBICS supplier with dynamic demobank#

Every protocol supplier of this type is reachable under POST /ebicsweb and by specifying its EBICS host name inside the EBICS message.

As of the internal representation, Sandbox keeps a database table called EbicsHostsTable that does not point at any demobank. Such table is the one that provides the bank’s EBICS private keys and has no business implications.

10.38.6.2.1. CCT (Payment initiations)#

This handler gets the bank account directly from the IBAN that was carried along the pain.001, therefore – as long as every IBAN is unique – this works with any demobank that hosts such IBAN. The EBICS subscriber public keys are extracted differently: they come from the tuple [userID, partnerID, systemID?] held in the request. Hence as long as such tuple is unique for each subscriber (Sandbox checks that), even the subscriber public keys are found regardless of the demobank name.

Note

The ‘context’ object found via the [userID, partnerID, systemID?] tuple has also a reference to the bank account. The consistency with the other bank account reference returned by the IBAN is currently NOT checked.

10.38.6.2.2. C52 (transactions report)#

This handler gets the reference to the subscriber public keys and bank account via the [userID, partnerID, systemID?] tuple. It then uses this bank account label to find the transactions that belong to the subscriber that made the request.

Note

The current implementation does NOT uses any demobank name along the transactions research: only the bank account label. This can lead to ambiguity, in case two different demobanks host respectively one bank account under the same label. This is not possible however in the current version, as Sandbox only admits one default demobank.

10.38.7. Alternatives#

Drop support for multitenancy banking. What is the benefit of this anyway?