From 844015cc5721430fe935ba73e69404ff66acadfc Mon Sep 17 00:00:00 2001 From: MS Date: Tue, 31 Oct 2023 14:25:23 +0100 Subject: Removing some obsolete libeufin docs. --- libeufin/bank-transport-ebics.rst | 55 ----- libeufin/circuit-cli-commands.rst | 152 ------------- libeufin/concepts.rst | 166 -------------- libeufin/index.rst | 7 +- libeufin/int-deployment-gv.rst | 71 ------ libeufin/iso20022.rst | 102 --------- libeufin/local-currencies-tutorial.rst | 401 --------------------------------- 7 files changed, 1 insertion(+), 953 deletions(-) delete mode 100644 libeufin/bank-transport-ebics.rst delete mode 100644 libeufin/circuit-cli-commands.rst delete mode 100644 libeufin/concepts.rst delete mode 100644 libeufin/int-deployment-gv.rst delete mode 100644 libeufin/local-currencies-tutorial.rst diff --git a/libeufin/bank-transport-ebics.rst b/libeufin/bank-transport-ebics.rst deleted file mode 100644 index 7d26cbc3..00000000 --- a/libeufin/bank-transport-ebics.rst +++ /dev/null @@ -1,55 +0,0 @@ -.. target audience: core developer - -The EBICS Bank Transport -======================== - -An EBICS bank transport in LibEuFin conceptually corresponds -to the "EBICS Subscriber" in EBICS terminology. - - -Bank Transport Setup --------------------- - -The following steps are required to set up an EBICS bank transport: - -1. The bank must set up the EBICS access for the user. - The bank will notify the user of the following parameters: - - * the URL of the EBICS server used by the bank - * the HostID of the bank within the EBICS server (sometimes one EBICS server hosts multiple banks) - * the PartnerID (typically identifies the owner of the bank account within the banking system) - * the UserID (typically identifies the person that accesses the bank account, can be different from the owner) - * the SystemID (optional and rarely used, basically a "sub-identity" of a subscriber when multiple technical - systems have access to the account via EBICS) - -2. The user enters the information from the list above in the setup dialog in the LibEuFin nexus (UI/CLI). - -3. The LibEuFin nexus generates cryptographic key material (3 RSA key pairs). - -4. The nexus sends the public keys electronically to the bank's EBICS server, together with the information - identifying the subscriber (PartnerID, UserID, SystemID). - -5. The user prints a document that contains the public key and hashes for all three key pairs. - The user then signs this document and sends it to the bank (physically/scanned). - -6. The bank receives the letter and verifies that the keys from the letter correspond - to the electronically sent keys. If they match, the bank sets the state of the - subscriber to "ready". - -7. The user now has to wait until the bank has set the EBICS subscriber state to "ready". - There is no in-band notification for this, but the Nexus can try downloading the bank's - cryptographic parameters. This will only succeed once the EBICS subscriber is set to "ready" - by the bank. - -8. The user should confirm the public keys of the bank received in the previous step. - Typically the bank gives the value of these public keys in an out-of-band channel. - -9. Now the user can finally use the EBICS bank transport. The first step after finishing - the setup should be to import the bank accounts accessible for this EBICS subscriber. - - -Alternative ways of setting up the EBICS bank transport are: - -* Importing from a backup. The backup contains metadata (EBICS URL, HostID, - UserId, ...) and the three passphrase-protected subscriber keys. -* Certificate-based setup (currently not supported by LibEuFin, only used in France) diff --git a/libeufin/circuit-cli-commands.rst b/libeufin/circuit-cli-commands.rst deleted file mode 100644 index 611922ee..00000000 --- a/libeufin/circuit-cli-commands.rst +++ /dev/null @@ -1,152 +0,0 @@ -CLI commands for the circuit API -################################ - -The following list shows all the CLI subcommands -acting as the Circuit API's client side. Each section -name is one subcommand available in this pattern: -``libeufin-cli sandbox demobank $subcommand``. - -Finally, each section name links to the related API -documentation of the endpoint being addressed. - -circuit-account-info -^^^^^^^^^^^^^^^^^^^^ - -Retrieve Circuit information about one account. Useful to get cash-out -address and contact details. - -Options: - --username TEXT Username of the account to retrieve. It defaults to - LIBEUFIN_SANDBOX_USERNAME and doesn't accept 'admin'. - --help Show this message and exit. - -circuit-accounts -^^^^^^^^^^^^^^^^ - - Gets the list of all the accounts managed by the Circuit. Only 'admin' - allowed - -Options: - --help Show this message and exit. - -circuit-cashout -^^^^^^^^^^^^^^^ - -Create a cash-out operation. If successful, the user gets a TAN. - -Options: - --subject TEXT Payment subject to associate to the outgoing and - incoming payments that are associated with this cash- - out operation. - --amount-debit TEXT Amount that will debited to the local currency - account, in the :X.Y format. [required] - --amount-credit TEXT Amount that will credited to the fiat currency - account, in the :X.Y format. [required] - --tan-channel TEXT Indicates how to send the TAN to the user: 'sms', - 'email' and 'file' are valid values. If missing, the - bank defaults to SMS. 'file' makes the server write - the TAN to /tmp/libeufin-cashout-tan.txt, normally - used for testing. - --help Show this message and exit. - - -circuit-cashout-abort -^^^^^^^^^^^^^^^^^^^^^ - -Abort a cash-out operation. Admin and author are allowed to request. - -Options: - --uuid TEXT UUID of the cash-out operation to abort. [required] - --help Show this message and exit. - - -circuit-cashout-confirm -^^^^^^^^^^^^^^^^^^^^^^^ - -Confirm a cash-out operation. Only the author is allowed (no admin). - -Options: - --tan TEXT TAN that authorizes the cash-out operaion. [required] - --uuid TEXT UUID of the cash-out operation to confirm. [required] - --help Show this message and exit. - - -circuit-cashout-details -^^^^^^^^^^^^^^^^^^^^^^^ - -Retrieve status information about one cash-out operation. Admin and author -are allowed to request. - -Options: - --uuid TEXT UUID of the cash-out operation to retrieve. [required] - --help Show this message and exit. - - -circuit-cashouts -^^^^^^^^^^^^^^^^ - -Gets the list of all the pending and confirmed cash-out operations. - -Options: - --help Show this message and exit. - - -circuit-delete-account -^^^^^^^^^^^^^^^^^^^^^^ - -Delete one account. Only available to the administrator and for accounts -with zero balance. - -Options: - --username TEXT account to delete [required] - --help Show this message and exit. - - -circuit-password-reconfig -^^^^^^^^^^^^^^^^^^^^^^^^^ - -Ask interactively to change the password. It needs administrator or owner -credentials - -Options: - --username TEXT Username whose password will change. Defaults to - LIBEUFIN_SANDBOX_USERNAME and doesn't accept 'admin' as a - value. - --help Show this message and exit. - - -circuit-reconfig -^^^^^^^^^^^^^^^^ - -Reconfigure an account with cash-out capabilities. It needs administrator -or owner credentials - -Options: - --phone TEXT Phone number for the SMS TAN - --email TEXT E-mail address for receiving the TAN - --cashout-address TEXT Payto address where to send fiat payments on cash- - outs [required] - --username TEXT Username associated with the account to reconfigure. - It defaults to LIBEUFIN_SANDBOX_USERNAME and doesn't - accept 'admin'. - --help Show this message and exit. - - -circuit-register -^^^^^^^^^^^^^^^^ - -Register a new account with cash-out capabilities. It needs administrator -credentials, and the new account password exported in -LIBEUFIN_NEW_CIRCUIT_ACCOUNT_PASSWORD. - -Options: - --username TEXT new account username [required] - --cashout-address TEXT Payto address where to send fiat payments on cash- - outs [required] - --name TEXT Legal name associated to the account. [required] - --phone TEXT SMS where to send the cash-out TAN. - --email TEXT E-mail address where to send the cash-out TAN. - --internal-iban TEXT Which IBAN to associate to this account. The IBAN - participates only in the local currency circuit. If - missing, the bank generates one. - --help Show this message and exit. diff --git a/libeufin/concepts.rst b/libeufin/concepts.rst deleted file mode 100644 index 6a251991..00000000 --- a/libeufin/concepts.rst +++ /dev/null @@ -1,166 +0,0 @@ -.. target audience: operator, developer - -################### -Conceptual Overview -################### - - -What is LibEuFin -================ - -The goal of LibEuFin is to make the development and testing of -FinTech applications easier. It hides implementation details -of complex legacy banking APIs behind a simple interface. - -LibEuFin Nexus and Sandbox --------------------------- - -LibEuFin has two main components: - -1. The LibEuFin nexus receives banking-related requests in a LibEuFin-specific - format via an HTTP API. It then translates those requests into interactions - with other banking APIs, abstracting away different underlying protocols and - hiding the complexity of the legacy protocols used by some banks. - -2. The LibEuFin sandbox implements the server side of protocols - that banks speak. It also emulates a *very*, *very* simple - core banking system to manage accounts and their balance. - The main use case for the sandbox is testing LibEuFin itself, - as well as applications developed with LibEuFin. - The sandbox has a JSON API to set it up for tests (creating bank - hosts, bank accounts, fake transactions). - - -High-Level Concepts -=================== - -Nexus Users ------------ - -The concept of a *nexus user* is used to implement access control to the -operations that the nexus provides. - -A user has a login name and a (salted, hashed) password. -This is the `HTTP basic auth `_ method. -(Other authentication methods could be added in the future.) - -A nexus user can be marked as *superuser*. All permission checks are skipped -for superusers. Only superusers are allowed to create/modify other users. - -Bank Accounts -------------- - -A *bank account* is the local representation of some bank account. -The information stored about it includes: - -* Local alias ("nickname") of the bank account -* Account identification (IBAN / BIC / account holder) -* A local mirror of the bank transaction history -* Payment requests, i.e. payments that have been locally requested, together - with their state (sent or not sent, acknowledged in bank statement or not) -* Error reports (e.g. failed payment requests, bank statement items that were not understood - by LibEuFin) -* A default bank connection (if configured) that is used by default - for operations on the account -* Other enabled "bank connections" (see definition below) - -Examples: - -.. code-block:: console - - # Download latest transactions via the default bank connection and store them locally - $ http -a $USER:$PASSWORD POST \ - https://example1.libeufin.tech/bank-accounts/my-acct/fetch-transactions - -Bank Connections ----------------- - -Bank connections connect the local LibEuFin bank account to the real bank. -The *bank connection* includes the following data: - -* Local alias ("nickname") of the bank connection -* The type of connection, i.e. the protocol used (EBICS, FinTS, loopback, sandbox) -* Protocol configuration (hostname, port, protocol sub-version/flags) -* Credentials to use the connection (e.g. password, EBICS subscriber keys) - -Bank connections provide the following actions: - -* Initial setup of the connection - -* Execute protocol-specific actions (e.g. EBICS: C53, C52, CCT, CRZ) - - * These actions do not have any effect on the LibEuFin local bank account. - To persist changes to the local bank account (transaction history, payment request status), - the bank connection must be invoked via the bank account. - -* Import bank accounts - - * Some bank connection protocols allow LibEuFin to query a list of bank - accounts that the connection has access to. This makes setup easier, - as the user doesn't have to create the local bank account manually. - -Examples: - -.. code-block:: console - - # Manually request the inter-day account report via the EBICS C52 order - $ http -a $USER:$PASSWORD POST \ - https://example1.libeufin.tech/bank-connections/my-ebics-testacct/ebics/download/C52 - - # Download available bank accounts that can be accessed through this connection, - # according to the bank server (with EBICS, does a HTD request). - # For each of them, create a bank account resource in LibEuFin. - $ http -a $USER:$PASSWORD POST \ - https://example1.libeufin.tech/bank-connection/my-ebics-testacct/fetch-accounts - -Facades -------- - -Facades allow extra domain-specific functionality to be implemented on top of users, bank accounts -and bank connections. A *facade* stores the following information: - -* Local name of the facade -* Facade type and options specific to the type -* Associated bank accounts and bank connections that can be accessed by the facade -* Internal tables used by the facade (i.e. facades are stateful) - -The only facade currently supported by LibEuFin is the "Taler Wire Gateway API" layer. -It provides a filtered view on the transaction history, a more restricted API to create payment -requests, and a mechanism to create a counter-transaction for incoming transactions that do -not conform to a certain format. - -Examples: - -.. code-block:: console - - # Request the Taler-specific history through the facade - $ http -a $USER:$PASSWORD \ - https://example1.libeufin.tech/facades/my-taler-wire-gw/taler/history/incoming - -Access Control -============== - -The goal of *access control* in LibEuFin is to allow the following scenarios: - -* The Nexus can be used by multiple clients for different bank accounts/connections - and these users can't access each other's bank accounts -* For monitoring / dashboard (e.g. Taler rejected transactions, blacklists), - some users should only be able to have read-only access. - -It is currently not planned to have more fine-grained permissions, such as -spending limits or more fine-grained read/write permissions. - -Users can be normal users or superusers. Permission checks do not apply to superusers, -and only superusers can create other users. - -Each top-level object (bank account, bank connection, facade) has a list of -nexus users with write access, and a list of users with read access. - -When using a bank connection through a bank account, permission checks must -succeed for both the bank account and the bank connection. - -This works differently for facades: A facade has a set of associated bank connections -and bank accounts it can access. Permissions on these associated objects -are checked when the facade is *created*. When invoking operations on the facade, -the nexus only checks if the current nexus user can access the facade and *not* the -underlying objects abstracted by the facade. diff --git a/libeufin/index.rst b/libeufin/index.rst index d139ca3b..4ccbe1aa 100644 --- a/libeufin/index.rst +++ b/libeufin/index.rst @@ -7,17 +7,12 @@ LibEuFin is a project providing free software tooling for European FinTech. :maxdepth: 1 :glob: - concepts - bank-transport-ebics ebics sepa iso20022 banking-protocols - transaction-identification frontend nexus-tutorial - local-currencies-tutorial - circuit-cli-commands - int-deployment-gv ebics3-test-tutorial performance + transaction-identification diff --git a/libeufin/int-deployment-gv.rst b/libeufin/int-deployment-gv.rst deleted file mode 100644 index b3a12935..00000000 --- a/libeufin/int-deployment-gv.rst +++ /dev/null @@ -1,71 +0,0 @@ -.. 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 7b1fed8c..3484c77d 100644 --- a/libeufin/iso20022.rst +++ b/libeufin/iso20022.rst @@ -110,105 +110,3 @@ Types of amounts in camt messages * EntryDetails announced posting amount * (not used by LibEuFin) - - -LibEuFin schema for account history ------------------------------------ - -FIXME: This is not complete yet. - -.. code-block:: typescript - - interface NexusTransactionsReponse { - entries: NexusAccountEntryItem[]; - } - - interface NexusAccountEntryItem { - nexusEntryId: string; - - // Serial number that will increase with each update - // to the entry. - nexusStatusSequenceId: number; - - entry: AccountEntryItem; - } - - interface AccountEntryItem { - - // At least one of entryId or accountServicerRef - // must be non-null - entryId?: string; - accountServicerRef?: string; - - creditDebitIndicator: "credit" | "debit"; - amount: string; - currency: string; - instructedAmountDetails?: { - amount: string; - currency: string; - currencyExchange?: { - sourceCurrency: string; - targetCurrency: string; - unitCurrency: string; - exchangeRate: string; - contractId: string; - quotationDate: string; - }; - }; - status: "booked" | "pending" | "info"; - valueDate?: string; - bookingDate?: string; - mandateId?: string; - endToEndId?: string; - messageId?: string; - - creditor?: Party - creditorAgent?: FinancialInstitution; - creditorAccount?: FinancialInstitution; - - debtor?: Party - debtorAgent?: FinancialInstitution; - debtorAccount?: FinancialInstitution; - - unstructuredRemittanceInformation?: string; - bankTransactionCode: BankTransactionCode; - } - - interface Party { - name?: string; - partyType: "private" | "organization"; - otherId?: { - id: string; - schemeName?: string; - issuer?: string; - }; - } - - interface Account { - name?: string; - currency?: string; - otherId?: { - id: string; - schemeName?: string; - issuer?: string; - }; - } - - interface FinancialInstitution { - type: "financial-institution"; - name?: string; - bic?: string; - otherId?: { - id: string; - schemeName?: string; - issuer?: string; - }; - } - - interface BankTransactionCode { - domain?: string; - family?: string; - subfamily?: string; - proprietaryIssuer?: string; - proprietaryCode?: string; - } diff --git a/libeufin/local-currencies-tutorial.rst b/libeufin/local-currencies-tutorial.rst deleted file mode 100644 index 9fa8be99..00000000 --- a/libeufin/local-currencies-tutorial.rst +++ /dev/null @@ -1,401 +0,0 @@ -Create a local currency (experimental) -###################################### - -This tutorial shows how to setup LibEuFin to act as the -bank of a local currency. The main features include the -registration and removal of user accounts *(only) by the -admin*, and the possibility to convert the local currency -into fiat (a.k.a. cashing out). - -The banking capabilities are offered by a LibEuFin service -called *Sandbox*. In particular, the tutorial relies on the -:ref:`Core Bank API `. More information about libEufin -can be found in the :doc:`How-To page `. - -The following sections show how to install and launch Sandbox -either `from sources `_, or `with Docker `_. - - -.. _install-from-sources: - -Install and config from sources -=============================== - -First :ref:`build LibEuFin `. - -If the installation succeeded, configure *Sandbox* with the -following command. - -.. code-block:: console - - $ export LIBEUFIN_SANDBOX_DB_CONNECTION=postgres:///libeufin - $ libeufin-sandbox config --currency NB --without-registrations default - -.. note:: - - The ``--without-registrations`` option allows *only the administrator* - to add new accounts. Without this option, other APIs may offer - unrestricted registrations. - -If the configuration step succeeded, Sandbox should be ready to serve the -bank for a currency named *NB*. - -In following step, we launch Sandbox by setting the administrator -password as ``secret``. - -.. note:: - - The following command launches Sandbox so that it writes - TANs on the filesystem to ease the cash-out operations without - relying on an `actual e-mail or SMS provider `_. -.. code-block:: console - - $ export LIBEUFIN_SANDBOX_ADMIN_PASSWORD=secret - $ libeufin-sandbox serve --port 5016 - -If Sandbox is running, jump to `this part `_. - -.. _docker-setup: - - -Install and config with Docker -============================== - -First, clone the deployment repository: - -.. code-block:: console - - $ git clone git://git.taler.net/deployment - -Then navigate to the Docker image location: - -.. code-block:: console - - $ cd deployment/nlnet/task1 - -Now build the image with the following command. - -.. code-block:: console - - $ docker build -t nlnet . - -If the build step went well, the following command -should suffice to start Sandbox and NGINX, by mapping -the host's 8080 port to the container's 80. - -.. code-block:: console - - $ export LIBEUFIN_EXPOSED_PORT=8080 - $ docker run \ - -e LIBEUFIN_EXPOSED_PORT=$LIBEUFIN_EXPOSED_PORT \ - -p $LIBEUFIN_EXPOSED_PORT:80 \ - -it nlnet - -The previous command uses a default admin password of 'admin'. -Do **CHANGE** the admin password in a production scenario. The -following command shows how to start the services with custom -values. - -.. note:: - - Start the services this way to provide the environment - suitable for this tutorial. - -.. code-block:: console - - $ export MY_ADMIN_PASSWORD=secret - $ export LIBEUFIN_EXPOSED_PORT=8080 - $ docker run \ - -e LIBEUFIN_SANDBOX_ADMIN_PASSWORD=$MY_ADMIN_PASSWORD \ - -e CURRENCY=NB \ - -e LIBEUFIN_EXPOSED_PORT=$LIBEUFIN_EXPOSED_PORT \ - -v libeufin_data:/libeufin-data \ - -v /tmp:/tmp \ - -p $LIBEUFIN_EXPOSED_PORT:80 \ - -p 5016:5016 \ - -it nlnet - -In the example above, Docker: - -0. Sets the admin password to *secret* -1. Sets the currency to *NB* -2. Stores the database in a *volume*. This helps to - share the database between containers. -3. Mounts container's ``/tmp`` to the host's, to let - the reader obtain the file TAN in the same way the - source-based installation does. -4. Maps the host's 8080 to the container's 80 port. -5. Maps the host's 5016 to the container's 5016 port. - That lets the CLI reach Sandbox inside the container, - and therefore run the tutorial. - -By success, Web browsers get the UI by visiting **http://localhost:8080** - -The following command shows how to delete the database, -by deleting its volume. - -.. code-block:: console - - $ docker volume rm libeufin_data - -Note: the removal might fail because the exited containers -are seen as still using the container. Please refer to the Docker -documentation for further information. - -.. _after-installation: - -If Sandbox is running -===================== - -Sandbox should now be reachable on the port 5016. Check it with: - -.. code-block:: console - - $ curl http://localhost:5016 - -If Sandbox is correctly running, it should respond with a greeting message. -At this point, the administrator can add a new merchant to the bank with the -following command. - -.. note:: - - Consult :doc:`this document `, - to learn all the CLI commands that address the (Circuit) API - used in this tutorial. - -.. code-block:: console - - export LIBEUFIN_SANDBOX_USERNAME=admin - export LIBEUFIN_SANDBOX_PASSWORD=secret - export LIBEUFIN_SANDBOX_URL=http://localhost:5016/ - export LIBEUFIN_NEW_CIRCUIT_ACCOUNT_PASSWORD=shop-secret - - libeufin-cli \ - sandbox \ - demobank \ - circuit-register \ - --name "Circuit Shop" \ - --username circuit-shop \ - --cashout-address payto://iban/CH463312 \ - --internal-iban INT940993 - -If the previous step succeeded, the merchant should have -access to their bank account with the *circuit-shop* username -and *shop-secret* password. - -Check it by asking the merchant balance with the following command. -The two environment variables LIBEUFIN_SANDBOX_USERNAME and -LIBEUFIN_SANDBOX_PASSWORD instruct the CLI to authenticate as the -merchant. - - -.. _check-balance: - -.. code-block:: console - - export LIBEUFIN_SANDBOX_USERNAME=circuit-shop - export LIBEUFIN_SANDBOX_PASSWORD=shop-secret - - libeufin-cli sandbox demobank info --bank-account circuit-shop - -The expected response looks like the following one: - - -.. code-block:: console - - { - "balance" : { - "amount" : "NB:0", - "credit_debit_indicator" : "credit" - }, - "paytoUri" : "payto://iban/SANDBOXX/INT940993?receiver-name=Circuit+Shop", - "iban" : "INT940993" - } - -In the following example, the merchant creates a cash-out operation, -trying to convert 1 NB back to the fiat currency. The ``--amount-debit`` -option takes the amount that the merchant wants to be debited -in their local currency bank account, whereas the ``--amount-credit`` -option is the calculation of the conversion rates as expected -by the merchant. The two values will be checked by the bank along -this request, to make sure that both parties agree. - -.. note:: - - The current version has a fixed **0.95** conversion rate for cashing - out. Future version will make this value configurable. - -.. code-block:: console - - libeufin-cli \ - sandbox \ - demobank \ - circuit-cashout \ - --amount-debit=NB:1 \ - --amount-credit=CHF:0.95 \ - --tan-channel=file - -If the previous command succeeded, it returned a JSON looking -like the following, although most likely having a **different** -UUID. - -.. code-block:: console - - { - "uuid" : "de12389b-e477-4a0c-829e-f779c1cfb3a0" - } - -The *uuid* represents the cash-out operation being just created -and waiting to be confirmed with a TAN. - -.. note:: - - The current version provides **only** the local currency - side of such operation. In other words, the merchant can - now only see a deduction on their local currency bank account - but no incoming payment in their fiat bank account. Future - versions will implement this. - -Confirm now the cash-out operation by sending to the -bank the TAN found in the file ``/tmp/libeufin-cashout-tan.txt``. -Assuming that the TAN for it is ``WXYZ``, the next command will confirm -it to the bank (please, use **your** UUID). - -.. code-block:: console - - libeufin-cli \ - sandbox demobank circuit-cashout-confirm \ - --uuid de12389b-e477-4a0c-829e-f779c1cfb3a0 \ - --tan WXYZ - -Check now that the cash-out operation appears as a outgoing -transaction for the merchant: - -.. code-block:: console - - libeufin-cli \ - sandbox demobank list-transactions \ - --bank-account circuit-shop - -The expected output should contain one line like the -following. That witnesses that the cash-out was correctly -confirmed and scheduled to be transferred to the fiat -account. - -.. code-block:: console - - "subject" : "Cash-out of NB:1 to CHF:0.95" - -The next commands show how to delete one account from -the local currency circuit. For the deletion to succeed, -the account must have a balance of zero NB. Because -of the cash-out operation, the merchant has now -1 NB -to their account, therefore the deletion will fail. Check -it, as the administrator, with the following command - - -.. _delete-account: - -.. code-block:: console - - export LIBEUFIN_SANDBOX_USERNAME=admin - export LIBEUFIN_SANDBOX_PASSWORD=secret - - libeufin-cli \ - sandbox demobank \ - circuit-delete-account --username circuit-shop - -The expected output is: - -.. code-block:: console - - Unexpected response status: 412 - Response: { - "error" : { - "type" : "sandbox-error", - "description" : "Account circuit-shop doesn't have zero balance. Won't delete it" - } - } - - -The bank may now award 1 NB to the merchant to bring their -balance to zero and finally delete the account. With the following -command, the administrator awards 1 NB to the merchant. - -.. code-block:: console - - libeufin-cli \ - sandbox demobank new-transaction \ - --bank-account admin \ - --payto-with-subject "payto://iban/SANDBOXX/INT940993?message=bring-to-zero" \ - --amount NB:1 - -Check if the balance returned to zero with `this command `_, -and try again to delete the account `like already done `_ - -Now the deletion command should have succeeded! -Try to `ask the balance `_ again, and expect one -error like the following: - - -.. code-block:: console - - { - "error" : { - "type" : "util-error", - "description" : "Customer 'circuit-shop' not found" - } - } - - -.. note:: - - Every Circuit API endpoint is addressed by a CLI subcommand - whose name starts with ``circuit-``. The following command - shows them. - - .. code-block:: console - - libeufin-cli sandbox demobank | grep circuit - -.. _email-sms-setup: - -E-mail or SMS TAN setup ------------------------ - -SMS and E-mail TANs get sent via commands that -are invoked by the Sandbox. Sandbox learns about those commands -via optional parameters to the ``serve`` command. - -.. note:: - - Future versions will allow setting the external commands - via the configuration; follow `#7527 `_. - -Hence, starting Sandbox as shown in the following commands is -the **only** requirement to use the aforementioned TAN channels. - -For the SMS TAN: - -.. code-block:: console - - libeufin-sandbox serve --sms-tan sms_provider_command - -Alternatively, for the e-mail TAN: - -.. code-block:: console - - libeufin-sandbox serve --email-tan email_provider_command - -Both commands will be passed the TAN to STDIN and the target -phone number / e-mail address as their first command line argument. - -.. note:: - - The way the invoked commands interact with their providers - is out of the Sandbox scope. - -Finally, Libeufin ships two TAN commands as example. The e-mail -command relies on `GNU mail `_ and the SMS command -on the service offered by ``_. Check ``contrib/libeufin-tan-sms.sh`` -and ``contrib/libeufin-tan-email.sh`` in the Libeufin repository. -- cgit v1.2.3