bank API refactor

3 files changed, 1 insertions, 1406 deletions

diff --git a/core/api-bank-access.rst b/core/api-bank-access.rst
deleted file mode 100644
index 25dd6cae..00000000
--- a/core/api-bank-access.rst
+++ /dev/null
@@ -1,302 +0,0 @@
-..
-  This file is part of GNU TALER.
-
-  Copyright (C) 2014-2020 Taler Systems SA
-
-  TALER is free software; you can redistribute it and/or modify it under the
-  terms of the GNU Affero General Public License as published by the Free Software
-  Foundation; either version 2.1, or (at your option) any later version.
-
-  TALER is distributed in the hope that it will be useful, but WITHOUT ANY
-  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
-  A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.
-
-  You should have received a copy of the GNU Affero General Public License along with
-  TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
-
-  @author Florian Dold
-
-=====================
-Taler Bank Access API
-=====================
-
-This chapter describes the API that the GNU Taler demonstrator bank offers to access accounts.
-
-This API differs from the "Bank Integration API" in that it provides advanced API access to accounts, as opposed
-to enabling wallets to withdraw with a better user experience ("tight integration").
-
-
-------------------------
-Accounts and Withdrawals
-------------------------
-
-.. http:get:: ${BANK_API_BASE_URL}/public-accounts
-
-  Show those accounts whose histories are publicly visible.  For example,
-  accounts from donation receivers.  As such, this request is unauthenticated.
-
-  **Response**
-
-  **Details**
-
-  .. ts:def:: PublicAccountsResponse
-
-    interface PublicAccountsResponse {
-      publicAccounts: PublicAccount[]
-    }
-
-  .. ts:def:: PublicAccount
-
-    interface PublicAccount {
-      iban: string;
-      balance: string;
-      // The account name _and_ the username of the
-      // Sandbox customer that owns such a bank account.
-      account_label: string;
-    }
-
-The following endpoints require HTTP "Basic" authentication with the account
-name and account password, at least in the GNU Taler demo bank implementation.
-
-
-.. http:get:: ${BANK_API_BASE_URL}/accounts/${account_name}
-
-  Request the current balance of an account.  (New: ) In case of a public bank
-  account, no authentication is required.
-
-  **Response**
-
-  **Details**
-
-  .. ts:def:: Balance
-
-    interface Balance {
-      amount: Amount;
-      credit_debit_indicator: "credit" | "debit";
-    }
-
-  .. ts:def:: BankAccountBalanceResponse
-
-    interface BankAccountBalanceResponse {
-      // Available balance on the account.
-      balance: Balance;
-
-      // payto://-URI of the account. (New)
-      payto_uri: string;
-
-      // Number indicating the max debit allowed for the requesting user.
-      debit_threshold: string;
-    }
-
-
-.. http:post:: ${BANK_API_BASE_URL}/accounts/${account_name}/withdrawals
-
-  Create a withdrawal operation, resulting in a ``taler://withdraw`` URI.
-
-  **Request**
-
-  .. ts:def:: BankAccountCreateWithdrawalRequest
-
-    interface BankAccountCreateWithdrawalRequest {
-      // Amount to withdraw.
-      amount: Amount;
-    }
-
-  **Response**
-
-  .. ts:def:: BankAccountCreateWithdrawalResponse
-
-    interface BankAccountCreateWithdrawalResponse {
-      // ID of the withdrawal, can be used to view/modify the withdrawal operation.
-      withdrawal_id: string;
-
-      // URI that can be passed to the wallet to initiate the withdrawal.
-      taler_withdraw_uri: string;
-    }
-
-  :http:statuscode:`403 Forbidden`:
-    The operation was rejected due to insufficient funds.
-
-.. http:get:: ${BANK_API_BASE_URL}/accounts/${account_name}/withdrawals/${withdrawal_id}
-
-  Query the status of a withdrawal operation.
-
-  **Response**
-
-  **Details**
-
-  .. ts:def:: BankAccountGetWithdrawalResponse
-
-    interface BankAccountGetWithdrawalResponse {
-      // Amount that will be withdrawn with this withdrawal operation.
-      amount: Amount;
-
-      // Was the withdrawal aborted?
-      aborted: boolean;
-
-      // Has the withdrawal been confirmed by the bank?
-      // The wire transfer for a withdrawal is only executed once
-      // both ``confirmation_done`` is ``true`` and ``selection_done`` is ``true``.
-      confirmation_done: boolean;
-
-      // Did the wallet select reserve details?
-      selection_done: boolean;
-
-      // Reserve public key selected by the exchange,
-      // only non-null if ``selection_done`` is ``true``.
-      selected_reserve_pub: string | null;
-
-      // Exchange account selected by the wallet, or by the bank
-      // (with the default exchange) in case the wallet did not provide one
-      // through the Integration API.
-      selected_exchange_account: string | null;
-    }
-
-
-.. http:post:: ${BANK_API_BASE_URL}/accounts/${account_name}/withdrawals/${withdrawal_id}/abort
-
-  Abort a withdrawal operation.  Has no effect on an already aborted withdrawal operation.
-
-  :http:statuscode:`200 OK`: The withdrawal operation has been aborted.  The response is an empty JSON object.
-  :http:statuscode:`409 Conflict`:  The reserve operation has been confirmed previously and can't be aborted.
-
-
-.. http:post:: ${BANK_API_BASE_URL}/accounts/${account_name}/withdrawals/${withdrawal_id}/confirm
-
-  Confirm a withdrawal operation.  Has no effect on an already confirmed withdrawal operation.
-  This call is responsible of wiring the funds to the exchange.
-
-  **Response**
-
-  :http:statuscode:`200 OK`:
-     The withdrawal operation has been confirmed.  The response is an empty JSON object.
-  :http:statuscode:`409 Conflict`:
-     The withdrawal has been aborted previously and can't be confirmed.
-  :http:statuscode:`422 Unprocessable Entity` (New):
-     The withdraw operation cannot be confirmed because no exchange and reserve public key selection happened before.
-
-------------
-Transactions
-------------
-
-.. http:get:: ${BANK_API_BASE_URL}/accounts/${account_name}/transactions
-
-   Retrieve a subset of transactions related to $account_name.  Without
-   query parameters, it returns the last 5 transactions.
-
-   **Request**
-
-   :query long_poll_ms: Optional number to express how many milliseconds the server
-     should wait for at least one result to be shown.  If not given, the server
-     responds immediately, regardless of the result.
-   :query page: page number starting from 1.  Page 1 has the latest transactions
-     and 1 is the default value.
-   :query size: how many transactions per page.  It must be at least 1 and defaults to 5.
-   :query from_ms: Optional.  Filters the results to transactions *from* (inclusively) this
-     timestamp in milliseconds
-   :query until_ms: Optional.  Filters the results to transactions *until* (inclusively) this
-     timestamp in milliseconds
-
-   **Response**
-
-   .. ts:def:: BankAccountTransactionsResponse
-
-     interface BankAccountTransactionsResponse {
-       transactions: BankAccountTransactionInfo[];
-     }
-
-.. http:get:: ${BANK_API_BASE_URL}/accounts/${account_name}/transactions/${transaction_id}
-
-   **Response**
-
-   Retrieve the transaction whose identifier is ``transaction_id``,
-   in the following format:
-
-   .. ts:def:: BankAccountTransactionInfo
-
-     interface BankAccountTransactionInfo {
-
-       creditor_iban: string;
-       creditor_bic: string; // Optional
-       creditor_name: string;
-
-       debtor_iban: string;
-       debtor_bic: string;
-       debtor_name: string;
-
-       amount: number;
-       currency: string;
-       subject: string;
-
-       // Transaction unique ID.  Matches
-       // $transaction_id from the URI.
-       uid: string;
-       direction: "DBIT" | "CRDT";
-       date: Timestamp;
-     }
-
-
-.. http:post:: ${BANK_API_BASE_URL}/accounts/${account_name}/transactions
-
-   Create a new transaction where the bank account with the label ``account_name`` is **debited**.
-
-   **Request**
-
-   .. ts:def:: BankAccountTransactionCreate
-
-      interface CreateBankAccountTransactionCreate {
-
-        // Address in the Payto format of the wire transfer receiver.
-        // It needs at least the 'message' query string parameter.
-        payto_uri: string;
-
-        // Transaction amount (in the $currency:x.y format), optional.
-        // However, when not given, its value must occupy the 'amount'
-        // query string parameter of the 'payto' field.  In case it
-        // is given in both places, the payto_uri's takes the precedence.
-        amount: string;
-      }
-
-   **Response**
-
-   :http:statuscode:`200 OK`:
-      the transaction has been created.
-
-   :http:statuscode:`400 Bad Request`:
-      the request was invalid or the payto://-URI used unacceptable features.
-
-.. http:delete:: ${BANK_API_BASE_URL}/accounts/${account_name}
-
-   Delete the bank account (and the customer entry) from the database.
-   Note, customer usernames and bank accounts have the same value.
-
-----------------------
-Registration (Testing)
-----------------------
-
-.. http:post:: ${BANK_API_BASE_URL}/testing/register
-
-  Create a new bank account.  This endpoint should be disabled for most deployments, but is useful
-  for automated testing / integration tests.
-
-  **Request**
-
-  .. ts:def:: BankRegistrationRequest
-
-    interface BankRegistrationRequest {
-      username: string;
-      password: string;
-      // Let the request specify the IBAN.  In this current
-      // version, the IBAN validity is NOT checked by the bank
-      // backend.  When missing, the IBAN is generated by the bank.
-      iban?: string;
-      // Name of the person who owns the account being made.
-      name?: string;
-      // Indicates whether the account is public or not.  Defaults to false
-      is_public?: boolean;
-    }
-
-
-  **Response**
-
-  :http:statuscode:`200 OK`:  Registration was successful.
diff --git a/core/api-bank-sandbox.rst b/core/api-bank-sandbox.rst
deleted file mode 100644
index d76ca2c4..00000000
--- a/core/api-bank-sandbox.rst
+++ /dev/null
@@ -1,1102 +0,0 @@
-..
-  This file is part of GNU TALER.
-
-  Copyright (C) 2014-2020 Taler Systems SA
-
-  TALER is free software; you can redistribute it and/or modify it under the
-  terms of the GNU Affero General Public License as published by the Free Software
-  Foundation; either version 2.1, or (at your option) any later version.
-
-  TALER is distributed in the hope that it will be useful, but WITHOUT ANY
-  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
-  A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.
-
-  You should have received a copy of the GNU Affero General Public License along with
-  TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
-
-.. target audience: developer, core developer
-
-.. _sandbox-api:
-
-Sandbox API
-###########
-
-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.
-
-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:
-
-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``.
-
-The client side of this API is offered both along the
-:doc:`CLI <../libeufin/circuit-cli-commands>` and the SPA.  The SPA is generally served
-along Sandbox ``/`` path.
-
-Accounts
---------
-
-.. _circuit-register:
-
-.. 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?: EmailAddress;
-
-       // Phone number.
-       phone?: PhoneNumber;
-     }
-
-
-   **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.
-
-
-.. _circuit-delete-account:
-
-.. 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.
-
-
-.. _circuit-reconfig:
-
-.. http:patch:: /accounts/$username
-
-   Allows the administrator and the user to reconfigure
-   the account data of ``$username``.
-
-   .. note::
-
-     Only the administrator has the rights to change the
-     user legal name.
-
-   **Request:**
-
-   .. ts:def:: CircuitAccountReconfiguration
-
-     interface CircuitAccountReconfiguration {
-
-       // Addresses where to send the TAN.
-       contact_data: CircuitContactData;
-
-       // Optional field.  'Payto' address pointing the
-       // bank account where to send payments, in case the
-       // user wants to convert the local currency back
-       // to fiat.  If this field is missing, any cash-out
-       // address will be deleted and the user loses their
-       // cash-out capability.
-       cashout_address?: string;
-
-       // Legal name associated with $username.  NOTE:
-       // only the administrator can change this value.
-       name?: string;
-     }
-
-   **Response:**
-
-   :http:statuscode:`204 No content`:
-     Operation successful.
-
-   :http:statuscode:`403 Forbidden`:
-     The rights to change ``$username`` are not sufficient.
-     That includes the case where a correctly authenticated
-     user tries to change their legal name.  It also
-     includes the case where 'admin' tries to change its
-     own account.
-
-   :http:statuscode:`404 Not found`:
-     The account pointed by ``$username``
-     was not found.
-
-
-.. _circuit-password-reconfig:
-
-.. 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.
-
-
-.. _circuit-account-list:
-
-.. http:get:: /accounts
-
-   Obtains a list of 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.
-
-   **Request:**
-
-   :query filter: *Optional.*
-     Pattern to filter on the account legal name.  Given
-     the filter 'foo', all the results will **contain**
-     'foo' in their legal name.  Without this option,
-     all the existing accounts are returned.
-
-   **Response:**
-
-   `CircuitAccounts <circuit-accounts_>`_
-
-   .. _circuit-accounts:
-
-   .. ts:def:: CircuitAccounts
-
-      interfaces CircuitAccounts {
-        customers: CircuitAccountMinimalData[];
-      }
-
-   .. ts:def:: Balance
-
-      interface Balance {
-        amount: Amount;
-        credit_debit_indicator: "credit" | "debit";
-      }
-
-   .. ts:def:: CircuitAccountMinimalData
-
-      interface CircuitAccountMinimalData {
-        // Username
-        username: string;
-
-        // Legal subject owning the account.
-        name: string;
-
-        // current balance of the account
-        balance: Balance;
-
-        // Number indicating the max debit allowed for the requesting user.
-        debit_threshold: string;
-      }
-
-   :http:statuscode:`200 OK`:
-     At least one account was found.
-
-   :http:statuscode:`204 No Content`:
-     No accounts were found for the given request.
-
-   :http:statuscode:`403 Forbidden`:
-     A ordinary user invoked this call.
-
-
-.. _circuit-account-info:
-
-.. http:get:: /accounts/$username
-
-   Obtains information relative to the account owned by
-   ``$username``.  The request is available to the administrator
-   and ``$username`` itself.
-
-   **Response:**
-
-   .. ts:def:: CircuitAccountData
-
-     interface CircuitAccountData {
-       // Username
-       username: string;
-
-       // IBAN hosted at Libeufin Sandbox
-       iban: string;
-
-       contact_data: CircuitContactData;
-
-       // Legal subject owning the account.
-       name: string;
-
-       // 'payto' address pointing the bank account
-       // where to send cashouts.  This field is optional
-       // because not all the accounts are required to participate
-       // in the merchants' circuit.  One example is the exchange:
-       // that never cashouts.  Registering these accounts can
-       // be done via the access API.
-       cashout_address?: string;
-     }
-
-   :http:statuscode:`403 Forbidden`:
-     The user is not allowed.
-
-Cashouts
---------
-
-.. _circuit-cashout:
-
-.. http:post:: /cashouts
-
-   Initiates a conversion to fiat currency.  The account to be
-   credited is the one specified at registration time via the
-   *cashout_address* parameter.  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.
-
-   .. note::
-
-     Consult the `cashout rates call <cashout-rates_>`_ to learn
-     about any applicable fee or exchange rate.
-
-   To test this operation without relying on any SMS/E-mail provider,
-   Libeufin offers two methods: defining an environment variable called
-   ``LIBEUFIN_CASHOUT_TEST_TAN`` or specifying the value ``file`` to
-   the ``tan_channel`` field of the `request object <cashout-request_>`_.
-   Assuming ``LIBEUFIN_CASHOUT_TEST_TAN`` is set to *T*, every */confirm*
-   operation can use *T* as the TAN.  Setting instead the ``tan_channel``
-   field to ``file`` will cause the server to (over)write every TAN to
-   ``/tmp/libeufin-cashout-tan.txt``.  If both are used, the environment
-   variable takes the precedence.
-
-
-   **Request:**
-
-   `CashoutRequest <cashout-request_>`_
-
-   .. ts:def:: TanChannel
-
-     enum TanChannel {
-       SMS = "sms",
-       EMAIL = "email",
-       FILE = "file"
-     }
-
-   .. _cashout-request:
-
-   .. ts:def:: CashoutRequest
-
-     interface CashoutRequest {
-
-       // 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;
-
-       // 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.
-
-
-.. _circuit-cashout-abort:
-
-.. 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.
-
-
-.. _circuit-cashout-confirm:
-
-.. 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:**
-
-   .. ts:def:: CashoutConfirm
-
-     interface CashoutConfirm {
-
-       // 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`:
-     At least the following two cases are possible
-     * an institutional user (``admin`` or ``bank``) tried the operation
-     * the user changed their cash-out address between the creation and the confirmation of ``$cashoutId``.
-   :http:statuscode:`412 Precondition failed`:
-     ``$cashoutId`` was already confirmed.
-
-
-.. http:get:: /cashouts/estimates
-
-  This endpoint shows how the bank would apply the cash-out
-  ratio and fee to one input amount.  Typically, frontends
-  ask this endpoint before creating cash-out operations.  There
-  is **no** financial consequence to this endpoint and only
-  registered users are allowed to request.  At least one of 
-  the two query parameters should be provided.  If both are
-  given, then the server checks their correctness.  Amounts
-  must include the currency.
-
-  **Request:**
-
-  :query amount_debit: this is the amount that the user will get
-    deducted from their regional bank account.
-
-  :query amount_credit: this is the amount that the user will receive
-    in their fiat bank account.
-
-  **Response:**
-
-  .. ts:def:: CashoutEstimate
-
-    interface CashoutEstimate {
-      // Amount that the user will get deducted from their regional
-      // bank account, according to the 'amount_credit' value.
-      amount_debit: Amount;
-      // Amount that the user will receive in their fiat
-      // bank account, according to 'amount_debit'.
-      amount_credit: Amount;
-    }
-
-
-  :http:statuscode:`200 Ok`:
-    Response contains the calculated values
-  :http:statuscode:`400 Bad request`:
-    Both parameters have been provided and the calculation is not correct,
-    or none of them has been provided.
-
-.. _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;
-       // Fiat currency.  That is the currency in which
-       // cash-out operations ultimately wire money.
-       fiat_currency: string;
-     }
-
-   .. ts:def:: RatiosAndFees
-
-     interface RatiosAndFees {
-       // Exchange rate to buy the circuit currency from fiat.
-       buy_at_ratio: LibeufinNumber; 
-       // Exchange rate to sell the circuit currency for fiat.
-       sell_at_ratio: LibeufinNumber;
-       // Fee to subtract after applying the buy ratio.
-       buy_in_fee: LibeufinNumber;
-       // Fee to subtract after applying the sell ratio.
-       sell_out_fee: LibeufinNumber;
-     }
-
-
-   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.
-
-
-.. _circuit-cashouts:
-
-.. http:get:: /cashouts
-
-  Returns the list of all the (pending and confirmed) cash-out operations.
-  Ordinary users can only use this endpoint to learn their *own* cash-out
-  operations.
-
-  **Request:**
-
-  :query account: *Optional.*
-    Filters the request to only get the cash-out operations related to
-    the account specified in this parameter.  Ordinary users must use
-    this option and pass their own username as the value.
-
-  **Response:**
-
-  .. ts:def:: Cashouts
-
-    interface Cashouts {
-      // Every string represents a cash-out operation UUID.
-      cashouts: string[];
-    }
-
-  :http:statuscode:`200 OK`:
-    At least one cash-out operation was found.
-
-  :http:statuscode:`204 No Content`:
-    No cash-out operations were found at the bank
-
-  :http:statuscode:`403 Forbidden`:
-    A ordinary user invoked this call either without
-    the ``account`` parameter or by passing to it someone
-    else's username.
-
-
-.. _circuit-cashout-details:
-
-.. 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;
-      // Amount debited to the circuit bank account.
-      amount_debit: Amount;
-      // Amount credited to the external bank account.
-      amount_credit: Amount;
-      // Transaction subject.
-      subject: string;
-      // Circuit bank account that created the cash-out.
-      account: string;
-      // Fiat bank account that will receive the cashed out amount.
-      cashout_address: string;
-      // Ratios and fees related to this cash-out at the time
-      // when the operation was created.
-      ratios_and_fees: RatiosAndFees;
-      // Time when the cash-out was created.
-      creation_time: number; // milliseconds since the Unix epoch
-      // Time when the cash-out was confirmed via its TAN.
-      // Missing or null, when the operation wasn't confirmed yet.
-      confirmation_time?: number | null; // milliseconds since the Unix epoch
-    }
-
-  .. 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
-^^^^^^^^^^
-
-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.
-
-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
-       host_id: string;
-
-       // userID
-       user_id: string;
-
-       // partnerID
-       partner_id: string;
-
-       // systemID, optional.
-       system_id: string;
-
-       // Label of the bank account to associate with
-       // this subscriber.
-       demobank_account_label: 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
-
-   Create a new EBICS host.
-
-   **Request:**
-
-   .. ts:def:: EbicsHostRequest
-
-     interface EbicsHostRequest {
-
-       // Ebics version.
-       host_id: string;
-
-       // Name of the host.
-       ebics_version: string;
-     }
-
-
-.. http:get:: /admin/ebics/hosts
-
-   Shows the list of all the hosts in the system.
-
-   **Response:**
-
-   .. ts:def:: EbicsHostResponse
-
-     interface EbicsHostResponse {
-
-       // shows the host IDs that are active in the system.
-       // The Ebics version *is* missing, but it's still available
-       // via the HEV message.
-       ebics_hosts: string[];
-     }
-
-.. http:post:: /admin/ebics/hosts/$hostID/rotate-keys
-
-   Overwrite the bank's Ebics keys with random ones.  This is entirely
-   meant for tests (as the Sandbox itself is) and no backup will be
-   produced along this operation.
-
-EBICS Subscribers
-^^^^^^^^^^^^^^^^^
-
-.. http:post:: /admin/ebics/bank-accounts
-
-  Associates a new bank account to an existing subscriber.
-
-  .. note::
-
-     This call allows to create a bank account without
-     any associated user profile!  That makes the basic auth
-     access to the financial data **only** possible for the
-     admin.
-
-  **Request:**
-
-  .. ts:def:: BankAccountRequest
-
-    interface BankAccountRequest {
-
-       // Ebics subscriber
-       subscriber: {
-         user_id: string;
-         partner_id: string;
-         system_id: string;
-       };
-
-       // IBAN
-       iban: string;
-
-       // BIC
-       bic: string;
-
-       // human name
-       name: string;
-
-       // 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
-       user_id: string;
-
-       // partnerID
-       partner_id: string;
-
-       // hostID
-       host_id: string;
-
-       // Label of the bank account
-       // associated with this Ebics subscriber.
-       demobank_account_label: string;
-     }
-
-.. http:post:: /admin/ebics/subscribers
-
-   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:: SubscriberRequestDeprecated
-
-     interface SubscriberRequestDeprecated {
-
-       // host ID
-       host_id: string;
-
-       // user ID
-       user_id: string;
-
-       // partner ID
-       partner_id: string;
-
-       // system ID, optional.
-       system_id: string;
-
-     }
-
-Bank accounts
-^^^^^^^^^^^^^
-
-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`.
-
-.. note::
-
-   The current version allows only one bank account per
-   customer, where the bank account name (also called 'label')
-   equals the owner's username.
-
-.. http:get:: /admin/bank-accounts
-
-   Give summary of all the bank accounts.  Only admin allowed.
-
-   **Response:**
-
-   .. ts:def:: AdminBankAccount
-
-     interface AdminBankAccount {
-
-       // IBAN
-       iban: string;
-
-       // BIC
-       bic: string;
-
-       // human name
-       name: string;
-
-       // bank account label
-       label: string;
-     }
-
-
-.. http:get:: /admin/bank-accounts/$accountLabel
-
-   Give information about a bank account.
-
-   **Response:**
-
-   .. ts:def:: AdminBankAccountBalance
-
-     interface AdminBankAccountBalance {
-       // Balance in the $currency:$amount format.
-       balance: Amount;
-       // IBAN of the bank account identified by $accountLabel
-       iban: string;
-       // BIC of the bank account identified by $accountLabel
-       bic: string;
-       // Mentions $accountLabel
-       label: string;
-     }
-
-.. http:post:: /admin/bank-accounts/$accountLabel
-
-  Create bank account.  Existing users without a bank account
-  can request too.
-
-  **Request:** :ts:type:`AdminBankAccount`
-
-Transactions
-^^^^^^^^^^^^
-
-.. http:get:: /admin/bank-accounts/$accountLabel/transactions
-
-   Inform about all the transactions of one bank account.
-
-   **Response:**
-
-   .. ts:def:: AdminTransactions
-
-     interface AdminTransactions {
-       payments: AdminTransaction[]; 
-     }
-
-   .. ts:def:: AdminTransaction
-
-     interface AdminTransaction {
-
-       // Label of the bank account involved in this payment.
-       account_label: string;
-
-       // Creditor IBAN
-       creditor_iban: string;
-
-       // Debtor IBAN
-       debtor_iban: string;
-
-       // UID given by one financial institute to this payment.
-       // FIXME: clarify whether that can be also assigned by
-       // the other party's institution. 
-       account_servicer_reference: string;
-
-       // ID of the Pain.001 that initiated this payment.
-       payment_information_id: string;
-
-       // Unstructured remittance information.
-       subject: string;
-
-       // Date of the payment in the HTTP header format.
-       date: string;
-
-       // The number amount as a string.
-       amount: string;
-
-       // BIC of the creditor IBAN.
-       creditor_bic: string;
-
-       // Legal name of the creditor.
-       creditor_name: string;
-
-       // BIC of the debtor IBAN.
-       debtor_bic: string;
-
-       // Legal name of the debtor.
-       debtor_name: string;
-
-       // Payment's currency
-       currency: string;
-
-       // Have values 'credit' or 'debit' relative
-       // to the requesting user.
-       credit_debit_indicator: string;
-     }
-
-.. 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.
-
-   **Request:**
-
-   .. ts:def:: AdminSimulateTransaction
-
-     interface AdminSimulateTransaction {
-
-       // Debtor IBAN.
-       debtor_iban: string;
-
-       // Debtor BIC.
-       debtor_bic: string;
-
-       // Debtor name.
-       debtor_name: string;
-
-       // Amount number (without currency) as a string.
-       amount: string;
-
-       // Payment subject.
-       subject: string;
-     }
-
-
-.. http:post:: /admin/payments/camt
-
-  Return the last camt.053 document from the requesting account.
-
-  **Request**
-
-  .. code-block:: tsref
-
-    interface CamtParams {
-
-      // label of the bank account being queried.
-      bankaccount: string;
-
-      // The Camt type to return.  Only '53' is allowed
-      // at this moment.
-      type: number;
-    }
-
-  **Response**
-
-  The last Camt.053 document related to the bank account
-  mentioned in the request body.
-
-
-.. _error-types:
-
-
-Errors
-======
-
-The JSON type coming along a non 2xx response is the following:
-
-.. ts:def:: SandboxError
-
-   interface SandboxError {
-     error: SandboxErrorDetail;
-   }
-
-.. ts:def:: SandboxErrorDetail
-
-   interface SandboxErrorDetail {
-
-     // String enum classifying the error.
-     type: ErrorType;
-
-     // Human-readable error description.
-     description: string;
-   }
-
-.. 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",
-
-     /**
-      * 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/core/api-bank.rst b/core/api-bank.rst
index 13524b72..16ed0679 100644
--- a/core/api-bank.rst
+++ b/core/api-bank.rst
@@ -30,9 +30,8 @@ Bank RESTful APIs
   api-bank-wire
   api-bank-merchant
   api-bank-integration
-  api-bank-access
+  api-libeufin-bank
   api-bank-nexus
-  api-bank-sandbox
   
 
 .. toctree::