diff options
Diffstat (limited to 'libeufin')
| -rw-r--r-- | libeufin/api-nexus.rst | 26 | ||||
| -rw-r--r-- | libeufin/api-sandbox-future.rst | 135 | ||||
| -rw-r--r-- | libeufin/api-sandbox.rst | 921 | ||||
| -rw-r--r-- | libeufin/demo-deployment-gv.rst | 49 | ||||
| -rw-r--r-- | libeufin/ebics.rst | 5 | ||||
| -rw-r--r-- | libeufin/index.rst | 1 | ||||
| -rw-r--r-- | libeufin/int-deployment-gv.rst | 71 | ||||
| -rw-r--r-- | libeufin/iso20022.rst | 11 | ||||
| -rw-r--r-- | libeufin/nexus-tutorial.rst | 339 |
9 files changed, 1221 insertions, 337 deletions
diff --git a/libeufin/api-nexus.rst b/libeufin/api-nexus.rst index 5f3e7a6c..b67a8ba2 100644 --- a/libeufin/api-nexus.rst +++ b/libeufin/api-nexus.rst @@ -204,7 +204,7 @@ Test API **Response** - The successful case should respond with a ``200 OK`` and a empty JSON body. + The successful case should respond with a ``200 OK`` and an empty JSON body. Bank Accounts @@ -238,17 +238,19 @@ manages payment initiations of the account and tracks the initiations of payment Get basic information about the bank account named ``my-acct``. - interface BankAccountInfoWithBalance { - // ID number of the database row being the default bank connection - // of `my-acct`. - defaultBankConnection: number; - // Payto://-URI of `my-acct`. - accountPaytoUri: string; - // Balance of `my-acct` as it was downloaded from the bank - // along the last Camt document. A human-readable message - // will inform the requester, should this value not be found. - lastSeenBalance: string; - } + .. ts:def:: BankAccountInfoWithBalance + + interface BankAccountInfoWithBalance { + // ID number of the database row being the default bank connection + // of ``my-acct``. + defaultBankConnection: number; + // Payto://-URI of ``my-acct``. + accountPaytoUri: string; + // Balance of ``my-acct`` as it was downloaded from the bank + // along the last Camt document. A human-readable message + // will inform the requester, should this value not be found. + lastSeenBalance: string; + } .. http:post:: {nexusBase}/bank-accounts/{acctid}/payment-initiations/{pmtid}/submit diff --git a/libeufin/api-sandbox-future.rst b/libeufin/api-sandbox-future.rst new file mode 100644 index 00000000..06dfc682 --- /dev/null +++ b/libeufin/api-sandbox-future.rst @@ -0,0 +1,135 @@ +Future Sandbox API +################## + +Resources. +^^^^^^^^^^ + +Sandbox serves the following resources: + + - Demobanks. + - Bank accounts. + - Subscribers. + - Transactions. + - Customers. + - Reports. + +The resources are subject to all CRUD operations, via by two +types of users: the 'admin' and the customers. The admin has +rights on all of them. + +One of the main differences with the previous versions is the +removal of the "/admin" initial component. If the administrator +authenticates for one operation, then this one is of type ``admin``: +no need for a dedicated and extra URI path component. + +For example, mocking transactions in the system was a typical +/admin-operation, but since transactions themselves are resources +and any resource is subject to CRUD operations, then mocking one +becomes just a ``C`` operation on the 'transactions' resources. If +a test case wants to simplify the authentication - by hard-coding +the credentials, for example - before mocking one transaction, then +it can impersonate the administrator. + +.. note:: + + ``POST``\ ing to an endpoint with a trailing ``$id`` means + modification of an existing resource. + +Demobanks +^^^^^^^^^ + +Demobanks are the main containers of all the other resources. +They take configuration values, like the currency for example. + +.. http:get:: /admin/demobanks +.. http:get:: /admin/demobanks/$id +.. http:post:: /admin/demobanks +.. http:post:: /admin/demobanks/$id +.. http:delete:: /admin/demobanks/$id + +Bank accounts. +^^^^^^^^^^^^^^ + +Bank accounts collect money of customers and participate +in transactions. + +The ``$base`` is one demobank, in the form ``/demobanks/$id``. +That is due because a bank account must inherit some defaults +from the demobank, like the currency. + +.. http:get:: $base/bankaccounts +.. http:get:: $base/bankaccounts/$id +.. http:post:: $base/bankaccounts +.. http:post:: $base/bankaccounts/$id +.. http:delete:: $base/bankaccounts/$id + +Subscribers. +^^^^^^^^^^^^ + +Subscribers are (optional) customers identities for protocols +other than the native one. + +A subscriber is not required to have a bank account "soon". Therefore, +it can be created, and later be linked to one bank account. For this +reason, the ``$base`` should not mention one bank account. + +.. note:: + + Creating a subscriber is a time-consuming operation that goes often + through slow channels, therefore it should basically never be done + more than once. + +.. http:get:: $base/subscribers +.. http:get:: $base/subscribers/$id +.. http:post:: $base/subscribers +.. http:post:: $base/subscribers/$id +.. http:delete:: $base/subscribers/$id + +Transactions. +^^^^^^^^^^^^^ + +Transactions are money movements between bank accounts. + +For convenience, ``$base`` **could** mention one bank account +to let customers see their transactions without defining "history" +query parameters: like ``$demobank/bankaccounts/$bankaccountId/transactions``. + +At the same time, transactions should be easy to query regardless +of whose bank account they involve -- for administrative reasons, for +example. Hence, a "global" URI scheme like ``$demobank/transactions?param=XXX`` +should be offered as well. + +.. http:get:: $base/transactions +.. http:get:: $base/transactions/$id +.. http:post:: $base/transactions +.. http:post:: $base/transactions/$id +.. http:delete:: $base/transactions/$id + +Customers. +^^^^^^^^^^ + +Customers are persons that **can** have one bank account. As +with subscribers, ``$base`` should not mention any bank account +so as to leave more flexibility to assign new bank accounts to +the same customer. + +.. http:get:: $base/customers +.. http:get:: $base/customers/$id +.. http:post:: $base/customers +.. http:post:: $base/customers/$id +.. http:delete:: $base/customers/$id + +Reports. +^^^^^^^^ + +Reports are persistent documents witnessing transactions. +A typical example is a Camt.053 statement. A report lives +even after a bank account gets deleted or a customer leaves +the bank, therefore ``$base`` should only mention a demobank +instance. + +.. http:get:: $base/reports +.. http:get:: $base/reports/$id +.. http:post:: $base/reports +.. http:post:: $base/reports/$id +.. http:delete:: $base/reports/$id diff --git a/libeufin/api-sandbox.rst b/libeufin/api-sandbox.rst index b75fcf8d..afbc3513 100644 --- a/libeufin/api-sandbox.rst +++ b/libeufin/api-sandbox.rst @@ -2,99 +2,530 @@ .. _sandbox-api: -Current Sandbox API -################### +Sandbox API +########### -.. - Current Sandbox endpoints. +Sandbox emulates a minimal bank, to provide EBICS access to test +`Taler <https://taler.net>`_. The top-level API defines two main +groups: `demobanks <Demobanks_>`_ and `legacy <Legacy API_>`_. +Currently, `error types <error-types_>`_ are common to both groups. - GET / - Welcome message. +Demobanks +========= + +Sandbox is designed to allow multiple *demobanks* being hosted, +where every demobank can have its own configuration (including +a different currency). A demobank has a name, although currently +only one demobank, named ``default``, is supported. Such demobank +activates the API segment ``/demobanks/default``, under which several +APIs are then served. The following sections describe all such APIs. + +Circuit API +^^^^^^^^^^^ + +This API offers to manage a selected group of users who act as businesses +for a local currency. Policies to disincentivize cashout operations may +also apply, making therefore this setup a *circuit* within a wider traditional +currency. + +For brevity, the list of response statuses for each endpoint may not be exhaustive. + +.. note:: + This API requires to **disable** ordinary registrations in the + configuration, to avoid other APIs from circumventing this registration + policy. See ``libeufin-sandbox config --help``. + +The following endpoints are served under ``/demobanks/default/circuit-api``. + +Accounts +-------- + +.. http:post:: /accounts + + Create a new bank account. Only the administrator is allowed. + + **Request:** + + .. ts:def:: CircuitAccountRequest + + interface CircuitAccountRequest { + // Username + username: string; + + // Password. + password: string; + + // Addresses where to send the TAN. If + // this field is missing, then the cashout + // won't succeed. + contact_data: CircuitContactData; + + // Legal subject owning the account. + name: string; + + // 'payto' address pointing the bank account + // where to send payments, in case the user + // wants to convert the local currency back + // to fiat. + cashout_address: string; + + // IBAN of this bank account, which is therefore + // internal to the circuit. Randomly generated, + // when it is not given. + internal_iban?: string; + } + + .. ts:def:: CircuitContactData + + interface CircuitContactData { + + // E-Mail address + email?: string; + + // Phone number. + phone?: string; + } + + + **Response:** + + :http:statuscode:`204 No content`: + The account was successfully created. + :http:statuscode:`400 Bad request`: + Input data was invalid. For example, the client specified a invalid + phone number or e-mail address. + :http:statuscode:`403 Forbidden`: + The response should indicate one of the following reasons. + + * A institutional username was attempted, like ``admin`` or ``bank``. + * A non admin user tried the operation. + + :http:statuscode:`409 Conflict`: + At least one registration detail was not available, + the error message should inform about it. + +.. http:delete:: /accounts/$username + + Delete the account whose username is ``$username``. The deletion + succeeds only if the balance is *zero*. Only the administrator is + allowed. + + **Response:** + + :http:statuscode:`204 No content`: + The account was successfully deleted. + :http:statuscode:`403 Forbidden`: + The administrator specified a institutional username, like + ``admin`` or ``bank``. + :http:statuscode:`404 Not found`: + The username was not found. + :http:statuscode:`412 Precondition failed`: + The balance was not zero. + + +.. http:patch:: /accounts/$username + + Allows the administrator and the user to reconfigure + the account data of ``$username``. + + **Request:** + + .. ts:def:: CircuitAccountReconfiguration + + interface CircuitAccountReconfiguration { + + // Addresses where to send the TAN. + contact_data: CircuitContactData; + + // 'payto' address pointing the bank account + // where to send payments, in case the user + // wants to convert the local currency back + // to fiat. + cashout_address: string; + } + + **Response:** + + :http:statuscode:`204 No content`: + Operation successful. + + :http:statuscode:`404 Not found`: + The account pointed by ``$username`` + was not found. + +.. http:patch:: /accounts/$username/auth + + Allows administrators *and* ordinary users to + change the account's password. + + **Request:** + + .. ts:def:: AccountPasswordChange + + interface AccountPasswordChange { + + // New password. + new_password: string; + } + + **Response:** + + :http:statuscode:`204 No content`: + Operation successful. + +.. http:get:: /accounts + + Obtains a list of all the accounts registered at the bank. + It returns only the information that this API handles, without + any balance or transactions list. The :doc:`Access API </core/api-bank-access>` + offers that. This request is only available to the administrator. + + **Response:** + + `CircuitAccounts <circuit-accounts_>`_ + + .. _circuit-accounts: + + .. ts:def:: CircuitAccounts + + interfaces CircuitAccounts { + customers: CircuitAccountMinimalData[]; + } + + .. ts:def:: CircuitAccountMinimalData + + interface CircuitAccountMinimalData { + // Username + username: string; + + // Legal subject owning the account. + name: string; - ** Camt debug ** + } - POST /admin/payments/camt - give last statement of requesting account +.. http:get:: /accounts/$username - ** Bank accounting ** + Obtains information relative to the account owned by + ``$username``. The request is available to the administrator + and ``$username`` itself. - POST /admin/bank-accounts/$accountLabel - create bank account (no EBICS involved) + **Response:** - GET /admin/bank-accounts - Give summary of all the bank accounts. + .. ts:def:: CircuitAccountData + + interface CircuitAccountData { + // Username + username: string; - GET /admin/bank-accounts/$accountLabel - give general information about a bank account + // IBAN hosted at Libeufin Sandbox + iban: string; - ** Transactions ** + contact_data: CircuitContactData; - POST /admin/bank-accounts/$accountLabel/simulate-incoming-transaction - Book one incoming transaction for $accountLabel. - The debtor (not required to be in the same bank) - information is taken from the request. + // Legal subject owning the account. + name: string; - GET /admin/bank-accounts/$accountLabel/transactions - Inform about all the transactions of one bank account. + // 'payto' address pointing the bank account + // where to send cashouts. + cashout_address: string; + } - POST /admin/bank-accounts/$accountLabel/generate-transactions - Generate one incoming and one outgoing transaction - for one bank account. + :http:statuscode:`403 Forbidden`: + The user is not allowed. - ** EBICS subscribers management ** +Cashouts +-------- - POST /admin/ebics/subscribers - Create a new EBICS subscriber. +.. http:post:: /cashouts - GET /admin/ebics/subscribers - Give details of all the EBICS subscribers in the bank. + Initiates a conversion to fiat currency. The target account + is the one specified at registration time. The account to be + debited is extracted from the authentication credentials. + The bank sends a TAN to the customer to let them confirm the + operation. The request is only available to ordinary users, not + to the administrator. - POST /admin/ebics/bank-accounts - Create a *new* bank account and link it with a existing - EBICS subscriber. + .. note:: + + Consult the `cashout rates call <cashout-rates_>`_ to learn + about any applicable fee or exchange rate. - ** EBICS host management ** + **Request:** - POST /admin/ebics/hosts/$hostID/rotate-keys - Change the bank's keys used in EBICS communication. + `CashoutRequest <cashout-request_>`_ - POST /admin/ebics/hosts - Create a new EBICS host. + .. ts:def:: TanChannel - GET /admin/ebics/hosts - Show details of all the EBICS hosts in the bank. + enum TanChannel { + SMS = "sms", + EMAIL = "email" + } - ** EBICS serving ** + .. _cashout-request: - POST /ebicsweb - Processes a EBICS request. + .. ts:def:: CashoutRequest - ** Taler .. ** + interface CashoutRequest { - GET /taler - Show one taler://-URI to initiate a withdrawal. + // Optional subject to associate to the + // cashout operation. This data will appear + // as the incoming wire transfer subject in + // the user's external bank account. + subject?: string; - - Taler integration API. + // That is the plain amount that the user specified + // to cashout. Its $currency is the circuit currency. + amount_debit: Amount; + + // That is the amount that will effectively be + // transferred by the bank to the user's bank + // account, that is external to the circuit. + // It is expressed in the fiat currency and + // is calculated after the cashout fee and the + // exchange rate. See the /cashout-rates call. + amount_credit: Amount; + + // Which channel the TAN should be sent to. If + // this field is missing, it defaults to SMS. + // The default choice prefers to change the communication + // channel respect to the one used to issue this request. + tan_channel?: TanChannel; + } + + **Response:** + + .. ts:def:: CashoutPending + + interface CashoutPending { + // UUID identifying the operation being created + // and now waiting for the TAN confirmation. + uuid: string; + } + + :http:statuscode:`202 Accepted`: + The cashout request was correctly created and + the TAN authentication now is pending. + :http:statuscode:`400 Bad request`: + The exchange rate was incorrectly applied. + :http:statuscode:`403 Forbidden`: + A institutional user (``admin`` or ``bank``) tried the operation. + :http:statuscode:`409 Conflict`: + The user did not share any contact data where to send the TAN. + :http:statuscode:`412 Precondition failed`: + The account does not have sufficient funds. + :http:statuscode:`503 Service unavailable`: + The bank does not support the TAN channel for this operation. + +.. http:post:: /cashouts/$cashoutId/abort + + Aborts the ``$cashoutId`` operation. Original author + *and* admin are both allowed. + + **Response:** + + :http:statuscode:`204 No content`: + ``$cashoutId`` was found in the *pending* state + and got successfully aborted. + :http:statuscode:`404 Not found`: + ``$cashoutId`` is not found. Note: that happens + also when ``$cashoutId`` got aborted before this request. + :http:statuscode:`412 Precondition failed`: + ``$cashoutId`` was already confirmed. + +.. http:post:: /cashouts/$cashoutId/confirm + + Confirms the ``$cashoutId`` operation by accepting its + TAN. The request should still be authenticated with + the users credentials. Only the original author is allowed. + + **Request:** - - Demobank configuration API. - ToDo. + .. ts:def:: CashoutConfirm + + interface CashoutConfirm { - - Taler access API. - ToDo. + // the TAN that confirms $cashoutId. + tan: string; + } + + **Response:** + + :http:statuscode:`204 No content`: + ``$cashoutId`` was found in the *pending* state and + got successfully confirmed. + :http:statuscode:`403 Forbidden`: + wrong TAN. + :http:statuscode:`404 Not found`: + ``$cashoutId`` is not found. Note: that happens + also when ``$cashoutId`` got aborted before this request. + :http:statuscode:`409 Conflict`: + A institutional user (``admin`` or ``bank``) tried the operation. + :http:statuscode:`412 Precondition failed`: + ``$cashoutId`` was already confirmed. + +.. _cashout-rates: + +.. http:get:: /config + + **Response:** + + .. ts:def:: Config + + interface Config { + // Name of this API, always "circuit". + name: string; + // API version in the form $n:$n:$n + version: string; + // Contains ratios and fees related to buying + // and selling the circuit currency. + ratios_and_fees: RatiosAndFees; + } + + .. ts:def:: RatiosAndFees + + interface RatiosAndFees { + // Exchange rate to buy the circuit currency from fiat. + buy_at_ratio: float; + // Exchange rate to sell the circuit currency for fiat. + sell_at_ratio: float; + // Fee to subtract after applying the buy ratio. + buy_in_fee: float; + // Fee to subtract after applying the sell ratio. + sell_out_fee: float; + } + + + Example. Given a circuit currency CC, a fiat currency FC, + a *sell_at_ratio* = 0.9 and *sell_out_fee* = 0.03, selling + 10 CC would result in the following FC: (10 * 0.9) - 0.03 + = 8.97 FC. On the other hand, given *buy_at_ratio* = 1.1 + and *buy_in_fee* = 0.01, a user wanting to spend 10 FC to + buy the CC would result in the following CC: (10 * 1.1) - + 0.01 = 10.99 CC. + + .. note:: + + the terms 'sell out' and 'cashout' may be used interchangeably. + +.. http:get:: /cashouts/$cashoutId + + Informs about the status of the ``$cashoutId`` operation. + The request is available to the administrator and the original author. + + **Response:** + + `CashoutStatusResponse <cashout-status_>`_ + + .. _cashout-status: + + .. ts:def:: CashoutStatus + + interface CashoutStatusResponse { + + status: CashoutStatus; + } + + .. ts:def:: CashoutStatus + + enum CashoutStatus { + + // The payment was initiated after a valid + // TAN was received by the bank. + CONFIRMED = "confirmed", + + // The cashout was created and now waits + // for the TAN by the author. + PENDING = "pending", + } + + **Response:** + + :http:statuscode:`404 Not found`: + The cashout operation was not found. That is + *also* the case of ``$cashoutId`` being an aborted + operation. + +Access API +^^^^^^^^^^ -EBICS. -^^^^^^ +Every endpoint is served under ``/demobanks/default/access-api``. +See :doc:`/core/api-bank-access`. This API allows users to access +their bank accounts and trigger Taler withdrawals. -Hosts. -++++++ +Integration API +^^^^^^^^^^^^^^^ + +Every endpoint is served under ``/demobanks/default/integration-api``. +See :doc:`/core/api-bank-integration`. This API handles the communication +with Taler wallets. + +Taler Wire Gateway API +^^^^^^^^^^^^^^^^^^^^^^ + +Served under ``/demobanks/default/taler-wire-gateway``. Currently, +only the :ref:`admin/add-incoming <twg-admin-add-incoming>` endpoint +is implemented. This endpoint allows testing, but the rest of +this API does never involve the Sandbox. + +EBICS API +^^^^^^^^^ + +.. _demobank-create-ebics-subscriber: + +.. http:post:: /demobanks/default/ebics/subscribers + + Allows (only) the *admin* user to associate a bank account + to a EBICS subscriber. If the latter does not exist, it is + created. + + **Request:** + + .. ts:def:: SubscriberRequest + + interface SubscriberRequest { + + // hostID + hostID: string; + + // userID + userID: string; + + // partnerID + partnerID: string; + + // systemID, optional. + systemID: string; + + // Label of the bank account to associate with + // this subscriber. + demobankAccountLabel: string; + } + +.. note:: + + The following endpoints are **not** served under the ``/demobank/default`` segment. + +Legacy API +========== + +This was the first API offered by Sandbox. It is used in +some test cases. One is hosted at the Wallet repository; other +MAY as well exist. + +Except of the main EBICS handler located at "/ebicsweb", all +the EBICS calls have to authenticate the 'admin' user via +the HTTP basic auth scheme. + +EBICS Hosts +^^^^^^^^^^^ .. http:post:: /admin/ebics/hosts - Creates a new Ebics host. + Create a new EBICS host. **Request:** - .. ts:def:: EbicsHostRequest + .. ts:def:: EbicsHostRequest interface EbicsHostRequest { @@ -112,7 +543,7 @@ Hosts. **Response:** - .. ts:def:: EbicsHostResponse + .. ts:def:: EbicsHostResponse interface EbicsHostResponse { @@ -128,9 +559,8 @@ Hosts. meant for tests (as the Sandbox itself is) and no backup will be produced along this operation. - -Subscribers. -++++++++++++ +EBICS Subscribers +^^^^^^^^^^^^^^^^^ .. http:post:: /admin/ebics/bank-accounts @@ -138,12 +568,16 @@ Subscribers. **Request:** - .. ts:def:: BankAccountRequest + .. ts:def:: BankAccountRequest - interface BankAccountRequest { + interface BankAccountRequest { // Ebics subscriber - subscriber: string; + subscriber: { + userID: string; + partnerID: string; + systemID: string; + }; // IBAN iban: string; @@ -156,19 +590,51 @@ Subscribers. // bank account label label: string; + } + +.. http:get:: /admin/ebics/subscribers + Shows the list of all the subscribers in the system. + + **Response:** + + .. ts:def:: SubscribersResponse + + interface SubscribersResponse { + + subscribers: Subscriber[] } + .. ts:def:: Subscriber + + interface Subscriber { + + // userID + userID: string; + + // partnerID + partnerID: string; + + // hostID + hostID: string; + + // Label of the bank account + // associated with this Ebics subscriber. + demobankAccountLabel: string; + } .. http:post:: /admin/ebics/subscribers - Creates a new Ebics subscriber. + Create a new EBICS subscriber without associating + a bank account to it. This call is **deprecated**. + Follow `this page <https://bugs.gnunet.org/view.php?id=7507>`_ + for updates over the EBICS management REST design. **Request:** - .. ts:def:: SubscriberRequest + .. ts:def:: SubscriberRequestDeprecated - interface SubscriberRequest { + interface SubscriberRequestDeprecated { // hostID hostID: string; @@ -179,239 +645,238 @@ Subscribers. // partnerID partnerID: string; - // systemID + // systemID, optional. systemID: string; } +Bank accounts +^^^^^^^^^^^^^ -.. http:get:: /admin/ebics/subscribers - - Shows the list of all the subscribers in the system. - - **Response:** +The access to a particular bank account is granted either to the +owner or to admin, via the HTTP basic auth scheme. A 'owner' is +a registered customer, who is identified by a username. The +registration of customers is offered via the :doc:`/core/api-bank-access`. - .. ts:def:: SubscribersResponse +.. note:: - interface SubscribersResponse { + The current version allows only one bank account per + customer, where the bank account name (also called 'label') + equals the owner's username. - subscribers: Subscriber[] - } - - .. ts:def:: Subscriber +.. http:get:: /admin/bank-accounts - interface Subscriber { + Give summary of all the bank accounts. Only admin allowed. - // userID - userID: string; + **Response:** - // partnerID - partnerID: string; + .. ts:def:: AdminBankAccount - // hostID - hostID: string; + interface AdminBankAccount { - } + // IBAN + iban: string; + // BIC + bic: string; -Bank accounts. -^^^^^^^^^^^^^^ + // human name + name: string; -.. http:get:: /admin/bank-accounts + // bank account label + label: string; + } - Give summary of all the bank accounts. .. http:get:: /admin/bank-accounts/$accountLabel Give information about a bank account. + **Response:** -Main EBICS service. -^^^^^^^^^^^^^^^^^^^ + .. ts:def:: AdminBankAccountBalance -.. http:post:: /ebicsweb + interface AdminBankAccountBalance { + // Balance in the $currency:$amount format. + balance: string; + // IBAN of the bank account identified by $accountLabel + iban: string; + // BIC of the bank account identified by $accountLabel + bic: string; + // Mentions $accountLabel + label: string; + } - Serves all the Ebics requests. +.. http:post:: /admin/bank-accounts/$accountLabel + Create bank account. Existing users without a bank account + can request too. -Transactions. -^^^^^^^^^^^^^ + **Request:** :ts:type:`AdminBankAccount` -JSON. -+++++ +Transactions +^^^^^^^^^^^^ .. http:get:: /admin/bank-accounts/$accountLabel/transactions Inform about all the transactions of one bank account. -.. http:post:: /admin/bank-accounts/$accountLabel/generate-transactions + **Response:** + + .. ts:def:: AdminTransactions + + interface AdminTransactions { + payments: AdminTransaction[]; + } - Generate one incoming and one outgoing transaction for one bank account. + .. ts:def:: AdminTransaction + + interface AdminTransaction { -.. http:post:: /admin/bank-accounts/$accountLabel/simulate-incoming-transaction + // Label of the bank account involved in this payment. + accountLabel: string; - Book one incoming transaction for $accountLabel. - The debtor (not required to be in the same bank) - information is taken from the request. + // Creditor IBAN + creditorIban: string; + // Debtor IBAN + debtorIban: string; -Camt. -+++++ + // UID given by one financial institute to this payment. + // FIXME: clarify whether that can be also assigned by + // the other party's institution. + accountServicerReference: string; -.. http:post:: /admin/payments/camt + // ID of the Pain.001 that initiated this payment. + paymentInformationId: string; - Return the last statement of the requesting account. + // Unstructured remittance information. + subject: string; - **Request** + // Date of the payment in the HTTP header format. + date: string; + + // The number amount as a string. + amount: string; + + // BIC of the creditor IBAN. + creditorBic: string; - .. code-block:: tsref + // Legal name of the creditor. + creditorName: string; - interface CamtParams { + // BIC of the debtor IBAN. + debtorBic: string; - // label of the bank account being queried. - bankaccount: string; + // Legal name of the debtor. + debtorName: string; - // The Camt type to return. Only '53' is allowed - // at this moment. - type: number; + // Payment's currency + currency: string; + + // Have values 'credit' or 'debit' relative + // to the requesting user. + creditDebitIndicator: string; } - **Response** +.. http:post:: /admin/bank-accounts/$accountLabel/generate-transactions + + Generate one incoming and one outgoing transaction for the bank account + identified by ``$accountLabel``. Only admin allowed. + +.. http:post:: /admin/bank-accounts/$accountLabel/simulate-incoming-transaction + + Book one incoming transaction for $accountLabel. + The debtor (not required to be in the same bank) + information is taken from the request. Only admin allowed. - The expected Camt.053 document. + **Request:** + + .. ts:def:: AdminSimulateTransaction -Future Sandbox API -################## + interface AdminSimulateTransaction { -Resources. ----------- + // Debtor IBAN. + debtorIban: string; -Sandbox serves the following resources: + // Debtor BIC. + debtorBic: string; - - Demobanks. - - Bank accounts. - - Subscribers. - - Transactions. - - Customers. - - Reports. - -The resources are subject to all CRUD operations, via by two -types of users: the 'admin' and the customers. The admin has -rights on all of them. + // Debtor name. + debtorName: string; -One of the main differences with the previous versions is the -removal of the "/admin" initial component. If the administrator -authenticates for one operation, then this one is of type `admin`: -no need for a dedicate and extra URI part. + // Amount number (without currency) as a string. + amount: string; -For example, mocking transactions in the system was a typical -/admin-operation, but since transactions themselves are resources -and any resource is subject to CRUD operations, then mocking one -becomes just a `C` operation on the 'transactions' resources. If -a test case wants to simplify the authentication - by hard-coding -the credentials, for example - before mocking one transaction, then -it can impersonate the administrator. + // Payment subject. + subject: string; + } -.. note:: - ``POST``-ing to a endpoint with a trailing ``$id`` means - modification of a existing resource. +.. http:post:: /admin/payments/camt -Demobanks -^^^^^^^^^ + Return the last camt.053 document from the requesting account. -Demobanks are the main containers of all the other resources. -They take configuration values, like the currency for example. + **Request** -.. http:get:: /admin/demobanks -.. http:get:: /admin/demobanks/$id -.. http:post:: /admin/demobanks -.. http:post:: /admin/demobanks/$id -.. http:delete:: /admin/demobanks/$id + .. code-block:: tsref -Bank accounts. -^^^^^^^^^^^^^^ + interface CamtParams { -Bank accounts collect money of customers and participate -in transactions. + // label of the bank account being queried. + bankaccount: string; -The ``$base`` is one demobank, in the form ``/demobanks/$id``. -That is due because a bank account must inherit some defaults -from the demobank, like the currency. + // The Camt type to return. Only '53' is allowed + // at this moment. + type: number; + } -.. http:get:: $base/bankaccounts -.. http:get:: $base/bankaccounts/$id -.. http:post:: $base/bankaccounts -.. http:post:: $base/bankaccounts/$id -.. http:delete:: $base/bankaccounts/$id + **Response** -Subscribers. -^^^^^^^^^^^^ + The last Camt.053 document related to the bank account + mentioned in the request body. -Subscribers are (optional) customers identities for protocols -other than the native one. -A subscriber is not required to have a bank account `soon`. Therefore, -it can be created, and later be linked to one bank account. For this -reason, the ``$base`` should not mention one bank account. +.. _error-types: -.. note:: +====== +Errors +====== - Creating a subscriber is a time-consuming operation that goes often - through slow channels, therefore it should basically never be done - more than once. +The JSON type coming along a non 2xx response is the following: -.. http:get:: $base/subscribers -.. http:get:: $base/subscribers/$id -.. http:post:: $base/subscribers -.. http:post:: $base/subscribers/$id -.. http:delete:: $base/subscribers/$id +.. ts:def:: SandboxError -Transactions. -^^^^^^^^^^^^^ + interface SandboxError { + error: SandboxErrorDetail; + } -Transactions are money movements between bank accounts. +.. ts:def:: SandboxErrorDetail -For convenience, ``$base`` **could** mention one bank account -to let customers see their transactions without defining "history" -query parameters: like ``$demobank/bankaccounts/$bankaccountId/transactions``. + interface SandboxErrorDetail { -At the same time, transactions should be easy to query regardless -of whose bank account they involve -- for administrative reasons, for -example. Hence, a "global" URI scheme like ``$demobank/transactions?param=XXX`` -should be offered as well. + // String enum classifying the error. + type: ErrorType; -.. http:get:: $base/transactions -.. http:get:: $base/transactions/$id -.. http:post:: $base/transactions -.. http:post:: $base/transactions/$id -.. http:delete:: $base/transactions/$id + // Human-readable error description. + description: string; + } -Customers. -^^^^^^^^^^ +.. ts:def:: ErrorType + + enum ErrorType { + /** + * This error can be related to a business operation, + * a non-existent object requested by the client, or + * even when the bank itself fails. + */ + SandboxError = "sandbox-error", -Customers are persons that **can** have one bank account. As -with subscribers, ``$base`` should not mention any bank account -so as to leave more flexibility to assign new bank accounts to -the same customer. - -.. http:get:: $base/customers -.. http:get:: $base/customers/$id -.. http:post:: $base/customers -.. http:post:: $base/customers/$id -.. http:delete:: $base/customers/$id - -Reports. -^^^^^^^^ - -Reports are persistent documents witnessing transactions. -A typical example is a Camt.053 statement. A report lives -even after a bank account gets deleted or a customer leaves -the bank, therefore ``$base`` should only mention a demobank -instance. - -.. http:get:: $base/reports -.. http:get:: $base/reports/$id -.. http:post:: $base/reports -.. http:post:: $base/reports/$id -.. http:delete:: $base/reports/$id + /** + * It is the error type thrown by helper functions + * from the Util library. Those are used by both + * Sandbox and Nexus, therefore the actual meaning + * must be carried by the error 'message' field. + */ + UtilError = "util-error" + } diff --git a/libeufin/demo-deployment-gv.rst b/libeufin/demo-deployment-gv.rst deleted file mode 100644 index 49462579..00000000 --- a/libeufin/demo-deployment-gv.rst +++ /dev/null @@ -1,49 +0,0 @@ -.. target audience: operator, developer - -Deploying Taler with libEufin -############################# - -.. contents:: Table of Contents - -This guide shows the steps to set up libEufin as the bank -for Taler. At this stage, only three constant bank accounts -are allowed, and the withdrawal can be triggered via the -command line interface. - -This document is more a set of notes for internal use than -a actual document for system administrators. - -Deployment on Gv ----------------- - -After having pulled the latest code of deployment.git: - -.. code-block:: console - - # The step below destroys data! - $ rm -fr ~/taler-data/* - # For the step below, the environment must be called 'int'. - $ taler-deployment bootstrap - $ taler-deployment build - # The step below destroys data! - $ taler-deployment-prepare-with-eufin resetDb - $ taler-deployment-restart-with-eufin - -At this point, the file ~/libeufin_admin_password should exist -and contain the password for the 'admin' user of the Sandbox. This -user is *also* the one that can withdraw with Taler. - -Withdraw with Taler -------------------- - -.. code-block:: console - - $ http --auth admin:$password $hostname/eufin/sandbox/taler - -The previous step should have returned a taler://-URI that -can be passed to the wallet: - - -.. code-block:: console - - $ taler-wallet-cli handle-uri $taler_uri diff --git a/libeufin/ebics.rst b/libeufin/ebics.rst index 058804e1..7c1fa2ae 100644 --- a/libeufin/ebics.rst +++ b/libeufin/ebics.rst @@ -409,13 +409,14 @@ Formats ISO 20022 --------- -ISO 20022 is XML-based and defines the message format for many finance-related activities. +`ISO 20022 <https://www.iso20022.org/>`_ +is XML-based and defines the message format for many finance-related activities. ISO 20022 messages are identified by a message identifier in the following format: <business area> . <message identifier> . <variant> . <version> -Some financial instututions (such as the Deutsche Kreditwirtschaft) may decided to use +Some financial instututions (such as the Deutsche Kreditwirtschaft) have decided to use a subset of elements/attributes in a message, this is what the ``<variant>`` part is for. "Standard" ISO20022 have variant ``001``. diff --git a/libeufin/index.rst b/libeufin/index.rst index 0e184862..29cd7a0e 100644 --- a/libeufin/index.rst +++ b/libeufin/index.rst @@ -18,3 +18,4 @@ LibEuFin is a project providing free software tooling for European FinTech. frontend nexus-tutorial demo-deployment-gv + int-deployment-gv diff --git a/libeufin/int-deployment-gv.rst b/libeufin/int-deployment-gv.rst new file mode 100644 index 00000000..b3a12935 --- /dev/null +++ b/libeufin/int-deployment-gv.rst @@ -0,0 +1,71 @@ +.. target audience: operator, developer + +Deploying Taler with libEufin +############################# + +.. contents:: Table of Contents + +This document shows how to compile and run all +the Taler services (including libEuFin). + +Deployment on Gv +---------------- + +After having pulled the latest code of deployment.git: + +.. code-block:: console + + $ python3 deployment/bin/WIP/taler-local bootstrap + $ python3 deployment/bin/WIP/taler-local build + $ python3 deployment/bin/WIP/taler-local prepare + +The last step offers also a way to specify the database +name -- only the PostgreSQL at this time -- and the hostname +of the reverse proxy. See ``--help`` for more information. + +At this point, the services can be launched, and will be +served at ``$hostname/$service``. The following command +will launch all the services and show what ``$service`` +can be: + +.. code-block:: console + + $ python3 deployment/bin/WIP/taler-local launch + +.. note:: + + In this context, one reverse proxy gets launched + along all the Taler services and will dispatch any request + to ``$service`` to the respective Unix domain socket. + +Withdraw with Taler +------------------- + +The following command withdraws a fixed amount of 5 units of currency +to the CLI wallet: + +.. code-block:: console + + $ python3 deployment/bin/WIP/taler-local withdraw + +The requests will be addressed to the default Sandbox, unless +``--bank-host`` (and ``--bank-proto``) were given; see ``--help`` +for more information. + +.. note:: + + To test phone wallets, the option ``--with-qr-code`` + can be specified. That will print a QR code on screen, and + wait for the user's input before confirming the payment to + the Exchange. + +Taler Internal deployment +------------------------- + +One deployment is currently hosted at ``int.taler.net``. + +Withdraw: + +.. code-block:: console + + $ python3 deployment/bin/WIP/taler-local withdraw --bank-host int.taler.net --bank-proto https diff --git a/libeufin/iso20022.rst b/libeufin/iso20022.rst index a4c0bf7b..7b1fed8c 100644 --- a/libeufin/iso20022.rst +++ b/libeufin/iso20022.rst @@ -24,13 +24,14 @@ The specifics of this mapping are: of message elements in the same schema. -Why does LibEuFin not use ISO 20022? -==================================== +How does LibEuFin leverage ISO 20022? +===================================== -While LibEuFin can ingest ISO 20022 messages (camt.05x, pain.002) and generate -them (pain.001), it does not use ISO 20022 in its API and internal data model. +While LibEuFin can communicate ISO 20022 messages (camt.05x, pain.001) to +other parties, it does **not** model its own authored API and internal data +after the ISO 20022 standard. -Reasons for not using ISO 20022 directly are: +Objections to ISO20022: 1. Impedance mismatch. ISO 20022 messages do not map well to query/response APIs. diff --git a/libeufin/nexus-tutorial.rst b/libeufin/nexus-tutorial.rst index 51e0cd28..482b0f96 100644 --- a/libeufin/nexus-tutorial.rst +++ b/libeufin/nexus-tutorial.rst @@ -134,6 +134,9 @@ If you don't have access to a real bank account with an EBICS API, you can set up the sandbox. The sandbox is a simplistic and incomplete implementation of a core banking system with EBICS access to bank accounts. +The sandbox uses HTTP Basic auth, with username ``admin``. +Choose a password and set env var ``LIBEUFIN_SANDBOX_ADMIN_PASSWORD`` to it. + The sandbox relies on a database, which you must specify using a JDBC connection URI with the ``LIBEUFIN_SANDBOX_DB_CONNECTION`` environment variable, before invoking any commands. @@ -141,6 +144,7 @@ If this variable is not set, ``libeufin-sandbox`` complains and exits: .. code-block:: console + $ export LIBEUFIN_SANDBOX_ADMIN_PASSWORD=secret $ libeufin-sandbox serve DB connection string not found/valid in the env variable LIBEUFIN_SANDBOX_DB_CONNECTION. The following two examples are valid connection strings: @@ -149,99 +153,336 @@ If this variable is not set, ``libeufin-sandbox`` complains and exits: Only *SQLite* and *PostgreSQL (via TCP)* are supported right now. -For the following commands, the sandbox service must be running. -The sandbox service is started with the following command: +Before being usable, a Sandbox needs to be configured. This is done +by creating the ``default`` demobank. A demobank is a set of configuration +values associated to one name; in the example below, we'll create one +named ``default``, that is mandatory to have. + +.. note:: + + By design, many demobanks can be hosted by one running Sandbox, + although at the time of writing only the ``default`` one is supported. + +A default demobank having the EUR currency is created with the following command: + +.. code-block:: console + + $ export LIBEUFIN_SANDBOX_DB_CONNECTION=jdbc:sqlite:/tmp/libeufintestdb + $ libeufin-sandbox config --currency EUR default + +In order to use Taler, a default exchange needs to be configured. + +.. code-block:: console + + $ export LIBEUFIN_SANDBOX_DB_CONNECTION=jdbc:sqlite:/tmp/libeufintestdb + $ libeufin-sandbox default-exchange --demobank default $exchange_base_url $exchange_payto_address + +The sandbox service can now be started with the following command: .. code-block:: console + $ export LIBEUFIN_SANDBOX_ADMIN_PASSWORD=secret $ export LIBEUFIN_SANDBOX_DB_CONNECTION=jdbc:sqlite:/tmp/libeufintestdb $ libeufin-sandbox serve --port 5016 +The instructions below hook Nginx to the Sandbox: + +.. code-block:: nginx + + redirect / to /demobanks/default; + rewrite ^/$ https://$host/demobanks/default; + location / { + proxy_set_header Host $host; + proxy_set_header X-Forwarded-Host $host; + proxy_set_header X-Forwarded-Proto "https"; + proxy_set_header X-Forwarded-Prefix "/"; + proxy_pass http://localhost:5016/; + } + To reset the state of the sandbox, delete the database. For invocations of the LibEuFin command-line interface tool (``libeufin-cli``), -the following environment variable must be set to the URL of the sandbox -service: +the following environment variables must be set to the authentication +information, and the URL of the sandbox service: .. code-block:: console - $ export LIBEUFIN_SANDBOX_URL=http://localhost:5016/ + $ export LIBEUFIN_SANDBOX_USERNAME=admin + $ export LIBEUFIN_SANDBOX_PASSWORD=secret + $ export LIBEUFIN_SANDBOX_URL=http://localhost:5016 +Note that the password is the same as for ``LIBEUFIN_SANDBOX_ADMIN_PASSWORD``. Verify that the sandbox is running: .. code-block:: console $ libeufin-cli sandbox check - { - "name" : "libeufin-sandbox", - "version" : "0.0.0-dev.0" - } + Hello, this is the Sandbox Now an EBICS host can be created: .. code-block:: console $ libeufin-cli sandbox ebicshost create --host-id testhost + $ libeufin-cli sandbox ebicshost list + { + "ebicsHosts" : [ "testhost" ] + } Note that most ``libeufin-cli`` subcommands will ask for input interactively if the respective value is not specified on the command line. -Next, create an EBICS subscriber (identified by the partner ID and user ID) for the host: +Next, register a user. For the ``libeufin-cli sandbox demobank register`` +command, the ``LIBEUFIN_SANDBOX_USERNAME`` and ``LIBEUFIN_SANDBOX_PASSWORD`` +are assumed to be ``jrluser`` and ``easy``, respectively. + +.. note:: + + All the following commands address the ``default`` demobank, see ``libeufin-cli sandbox demobank --help``. .. code-block:: console - $ libeufin-cli sandbox ebicssubscriber create \ - --host-id testhost --partner-id partner01 --user-id user01 + $ export LIBEUFIN_SANDBOX_USERNAME=jrluser + $ export LIBEUFIN_SANDBOX_PASSWORD=easy + $ libeufin-cli sandbox demobank register -Create a bank account for the subscriber and add a sample transaction: +Check the balance of the user just created: .. code-block:: console - $ libeufin-cli sandbox ebicsbankaccount create \ - --currency EUR \ - --iban DE18500105172929531888 \ - --bic INGDDEFFXXX \ - --person-name "Jane Normal" \ - --account-name "testacct01" \ - --ebics-host-id testhost \ - --ebics-user-id user01 \ - --ebics-partner-id partner01 + $ libeufin-cli sandbox \ + demobank info --bank-account jrluser + +With a user registered, we can now create an EBICS subscriber (identified by +the partner ID and user ID) for the host. This command requires admin +privileges, so ``LIBEUFIN_SANDBOX_USERNAME`` and ``LIBEUFIN_SANDBOX_PASSWORD`` +are reset back to ``admin`` and ``secret``, respectively. -The account name ``testacct01`` is the unique identifier of the account within +.. The plan is to replace the ‘sandbox ebicssubscriber list’ command + below with a ‘sandbox demobank show-ebicssubscriber’ command. + Need to implement it first! + +.. code-block:: console + + $ export LIBEUFIN_SANDBOX_USERNAME=admin + $ export LIBEUFIN_SANDBOX_PASSWORD=secret + $ libeufin-cli sandbox \ + demobank new-ebicssubscriber \ + --host-id testhost \ + --partner-id partner01 \ + --user-id user02 \ + --bank-account jrluser + $ libeufin-cli sandbox ebicssubscriber list + { + "subscribers" : [ { + "hostID" : "testhost", + "partnerID" : "partner01", + "userID" : "user02", + "systemID" : null, + "demobankAccountLabel" : "jrluser" + } ] + } + +The ``libeufin-cli sandbox demobank new-ebicssubscriber`` command +also creates an associated bank account. You can see it with command: + +.. code-block:: console + + $ libeufin-cli sandbox bankaccount list + [ { + "label" : "bank", + "name" : "Bank account owner's name", + "iban" : "DE895351", + "bic" : "SANDBOXX" + }, { + "label" : "jrluser", + "name" : "Bank account owner's name", + "iban" : "DE724881", + "bic" : "SANDBOXX" + } ] + +The account name ``jrluser`` is the unique identifier of the account within the sandbox. The EBICS parameters identify the subscriber that should have access to the bank account via EBICS. -To populate the account with some test transactions, run the following command -(note that we use the ``bankaccount`` subcommand, because there is no need to rely -on EBICS): +The account already has one transaction, the "Sign-up bonus" from the bank. +Note that in the following examples we transition to using the ``bankaccount`` +subcommand, because there is no need to rely on EBICS: .. code-block:: console - $ libeufin-cli sandbox bankaccount generate-transactions testacct01 + $ libeufin-cli sandbox bankaccount transactions jrluser + { + "payments" : [ { + "accountLabel" : "jrluser", + "creditorIban" : "DE724881", + "creditorBic" : "SANDBOXX", + "creditorName" : "Unknown", + "debtorIban" : "DE895351", + "debtorBic" : "SANDBOXX", + "debtorName" : "The Bank", + "amount" : "100", + "currency" : "EUR", + "subject" : "Sign-up bonus", + "date" : "Tue, 22 Feb 2022 00:04:15 GMT", + "creditDebitIndicator" : "credit", + "accountServicerReference" : "2NG75I0O", + "paymentInformationId" : null + } ] + } + +To populate the account with some more transactions, run the following command: .. code-block:: console - $ libeufin-cli sandbox bankaccount simulate-incoming-transaction testacct01 \ + $ libeufin-cli sandbox bankaccount generate-transactions jrluser + +.. code-block:: console + + $ libeufin-cli sandbox bankaccount simulate-incoming-transaction jrluser \ --debtor-iban DE06500105174526623718 \ --debtor-bic INGDDEFFXXX \ --debtor-name "Joe Foo" \ --subject "Hello World" \ --amount 10.50 -Payments to a sandbox bank account can be listed as follows: +Now the list of transactions has grown by several entries: + +.. code-block:: console + + $ libeufin-cli sandbox bankaccount transactions jrluser + { + "payments" : [ { + "accountLabel" : "jrluser", + "creditorIban" : "DE724881", + "creditorBic" : "SANDBOXX", + "creditorName" : "Unknown", + "debtorIban" : "DE895351", + "debtorBic" : "SANDBOXX", + "debtorName" : "The Bank", + "amount" : "100", + "currency" : "EUR", + "subject" : "Sign-up bonus", + "date" : "Tue, 22 Feb 2022 00:04:15 GMT", + "creditDebitIndicator" : "credit", + "accountServicerReference" : "2NG75I0O", + "paymentInformationId" : null + }, { + "accountLabel" : "jrluser", + "creditorIban" : "DE724881", + "creditorBic" : "SANDBOXX", + "creditorName" : "Creditor Name", + "debtorIban" : "DE64500105178797276788", + "debtorBic" : "DEUTDEBB101", + "debtorName" : "Max Mustermann", + "amount" : "22", + "currency" : "EUR", + "subject" : "sample transaction GSF7S5LC", + "date" : "Tue, 22 Feb 2022 01:26:18 GMT", + "creditDebitIndicator" : "credit", + "accountServicerReference" : "GSF7S5LC", + "paymentInformationId" : null + }, { + "accountLabel" : "jrluser", + "creditorIban" : "DE64500105178797276788", + "creditorBic" : "DEUTDEBB101", + "creditorName" : "Max Mustermann", + "debtorIban" : "DE724881", + "debtorBic" : "SANDBOXX", + "debtorName" : "Debitor Name", + "amount" : "10", + "currency" : "EUR", + "subject" : "sample transaction 1WUP303Q", + "date" : "Tue, 22 Feb 2022 01:26:18 GMT", + "creditDebitIndicator" : "debit", + "accountServicerReference" : "1WUP303Q", + "paymentInformationId" : null + }, { + "accountLabel" : "jrluser", + "creditorIban" : "DE724881", + "creditorBic" : "SANDBOXX", + "creditorName" : "Creditor Name", + "debtorIban" : "DE06500105174526623718", + "debtorBic" : "INGDDEFFXXX", + "debtorName" : "Joe Foo", + "amount" : "10.50", + "currency" : "EUR", + "subject" : "Hello World", + "date" : "Tue, 22 Feb 2022 01:26:41 GMT", + "creditDebitIndicator" : "credit", + "accountServicerReference" : "sandbox-ALQP8TXKJWRVKMAH", + "paymentInformationId" : null + } ] + } + +Lastly, you will want to schedule some tasks to run +periodically in the background. +This enables the Nexus to interact in (almost) real-time with the bank. .. code-block:: console - $ libeufin-cli sandbox bankaccount transactions testacct01 + $ libeufin-cli accounts task-schedule jrluser \ + --task-type submit \ + --task-name submit-payments-each-second \ + --task-cronspec "* * *" + $ libeufin-cli accounts task-schedule jrluser \ + --task-type fetch \ + --task-name fetch-reports-each-second \ + --task-cronspec "* * *" \ + --task-param-level report \ + --task-param-range-type latest + +The first task submits payments and the second fetches reports. +Both are specified to run every second (cronspec ``"* * *"``). +To reduce the frequency to every five seconds, use the cronspec ``"*/5 * *"`` +(remember to quote, to protect from shell filename expansion). .. note:: The sandbox is intended as a testing tool and thus not stable. +Disable registrations (experimental) +------------------------------------ + +Demobanks can disable/enable registrations for new users. +The responsible options are +``--with-registrations`` / ``--without-registrations``. + For more information on the available commands, use the built-in ``--help`` flag. The full functionality of the sandbox is available via the :ref:`Sandbox API <sandbox-api>`. +Register merchants for local currencies (experimental) +------------------------------------------------------ + +This feature allows to register merchants to participate +in a local currency circuit. After having installed the +Sandbox with the steps described above, the administrator +can now register new merchant accounts with the following +command. The main difference with ordinary registrations +is that this API offers to associate a `cash-out` address +to the account, so that merchants can convert the local +currency back to their fiat bank account. + +.. note:: + Disable ordinary registrations as described in the previous section, + to make sure that only the administrator can add new accounts. + +.. code-block:: console + + $ export LIBEUFIN_SANDBOX_USERNAME=admin + $ export LIBEUFIN_SANDBOX_PASSWORD=$password + $ export LIBEUFIN_NEW_CIRCUIT_ACCOUNT_PASSWORD=$circuit-account-password + $ libeufin-cli sandbox demobank circuit-register \ + --username=example-shop \ + --email=example-shop@example.com \ + --cashout-address=payto://iban/EXAMPLESHOP-FIAT-IBAN \ + --name="Example Shop" + + +If the command exited successfully, the new user should be +able to login with the ``$circuit-account-username`` and +``$circuit-account-password`` credentials. Run ``libeufin-cli sandbox demobank circuit-register --help``, for additional information about the other options. Connect Nexus with an EBICS account =================================== @@ -255,7 +496,12 @@ Only *SQLite* (e.g. ``jdbc:sqlite:/tmp/libeufintestdb``) and *PostgreSQL (via TC (e.g. ``jdbc:postgresql://localhost:$port/libeufintestdb?user=$username&password=$password``) are supported right now. -Use the following command to run the nexus service: +Use the following command to run the Nexus service: + + Neuxs defaults to *not* storing the messages that it downloads + from the bank. To revert this behaviour, export also the environment + variable ``LIBEUFIN_NEXUS_KEEP_BANK_MESSAGES`` to ``yes`` before + running the following command. .. code-block:: console @@ -264,8 +510,8 @@ Use the following command to run the nexus service: This assumes that the PostgreSQL service with a database called ``libeufindb`` listens on port 5433 -for requests from the nexus service. -The nexus service itself listens on port 5017. +for requests from the Nexus service. +The Nexus service itself listens on port 5017. Note that you must have the ``LIBEUFIN_NEXUS_DB_CONNECTION`` environment variable set for most uses of the libeufin-nexus command. @@ -290,14 +536,22 @@ to be defined in the environment: ``LIBEUFIN_NEXUS_URL``, ``LIBEUFIN_NEXUS_USERN and ``LIBEUFIN_NEXUS_PASSWORD``. In this example, ``LIBEUFIN_NEXUS_USERNAME`` should be set to ``foo``, and ``LIBEUFIN_NEXUS_PASSWORD`` to the value given for its password in the previous step (with the ``libeufin-nexus superuser`` command). The -``LIBEUFIN_NEXUS_URL`` could be given as ``http://localhost:5017/``. +``LIBEUFIN_NEXUS_URL`` could be given as ``http://localhost:5017``. -Next, we create a EBICS *bank connection* that nexus can use to communicate with the bank. +Next, we create a EBICS *bank connection* that Nexus can use to communicate with the bank. .. note:: For the sandbox setup in this guide, the ``EBICS_BASE_URL`` should be ``http://localhost:5016/ebicsweb``. + This is the value of environment variable + ``LIBEUFIN_SANDBOX_URL`` suffixed with ``/ebicsweb``, + since the sandbox will be providing EBICS services. + + Similarly, ``EBICS_HOST_ID`` should be ``testhost``, + and ``EBICS_PARTNER_ID`` should be ``partner01``. + For ``EBICS_USER_ID`` we will use ``user02`` (for account ``jrluser``), + and for ``CONNECTION_NAME``, we will use ``conn01``. .. code-block:: console @@ -310,7 +564,10 @@ Next, we create a EBICS *bank connection* that nexus can use to communicate with --ebics-user-id $EBICS_USER_ID \ $CONNECTION_NAME -If this step executes correctly, Nexus will have created all the cryptographic +If this step executes correctly +(use ``libeufin-cli connections list-connections`` +and ``libeufin-cli connections show-connection`` to check), +Nexus will have 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 *make a backup copy* of such keys. @@ -325,7 +582,7 @@ a backup copy* of such keys. $CONNECTION_NAME At this point, Nexus needs to both communicate its keys to the bank, and -download the bank's keys. This syncronization happens through the INI, HIA, and +download the bank's keys. This synchronization happens through the INI, HIA, and finally, HPB message types. After the electronic synchronization, the subscriber must confirm their keys @@ -394,7 +651,7 @@ list of transactions, and making a payment. Request history of transactions =============================== -The LibEuFin nexus keeps a local copy of the bank account's transaction +The LibEuFin Nexus keeps a local copy of the bank account's transaction history. Before querying transactions locally, it is necessary to request transactions for the bank account via the bank connection. @@ -449,18 +706,18 @@ in the next step, to **send the payment instructions to the bank**: .. code-block:: console - $ libeufin-cli accounts submit-payment \ + $ libeufin-cli accounts submit-payments \ --payment-uuid $UUID \ $LOCAL_ACCOUNT_NAME Automatic scheduling ==================== -With an EBICS bank connection, the LibEuFin nexus needs to regularly query for +With an EBICS bank connection, the LibEuFin Nexus needs to regularly query for new transactions and (re-)submit prepared payments. It is possible to schedule these tasks via an external task scheduler such as -cron(8). However, the nexus also has an internal task scheduling mechanism for +cron(8). However, the Nexus also has an internal task scheduling mechanism for accounts. |