taler-docs

api-corebank.rst (62447B)

---

 ..
   This file is part of GNU TALER.
 
   Copyright (C) 2014-2025 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
 
 .. _corebank-api:
 
 ====================
 Taler Core Bank API
 ====================
 
 .. contents:: Table of Contents
   :local:
 
 Introduction
 ------------
 
 The Libeufin bank provides a minimal core banking system.  In addition to that,
 it provides features for local/regional currencies.
 
 Version History
 ---------------
 
 The current protocol version is ``v11``.
 
 Android cashier app is currently targeting ``v9``.
 
 **Version history:**
 
 * ``v11``: Add observability API
 * ``v10``: Update two factor authentication API to match Merchant Backend API
 
 Config
 ------
 
 .. http:get:: /config
 
   Return the protocol version and configuration information about the bank.
   This specification corresponds to ``current`` protocol being version **v11**.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     Response is a `Config`.
 
   **Details:**
 
   .. ts:def:: Config
 
     interface Config {
       // Name of the API.
       name: "taler-corebank";
 
       // libtool-style representation of the Bank protocol version, see
       // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning
       // The format is "current:revision:age".
       version: string;
 
       // Bank display name to be used in user interfaces.
       // For consistency use "Taler Bank" if missing.
       // @since **v4**, will become mandatory in the next version.
       bank_name?: string;
 
       // Advertised base URL to use when you sharing an URL with another
       // program.
       // @since **v4**.
       base_url?: string;
 
       // If 'true' the server provides local currency conversion support
       // If 'false' some parts of the API are not supported and return 501
       allow_conversion: boolean;
 
       // If 'true' anyone can register
       // If 'false' only admin can
       allow_registrations: boolean;
 
       // If 'true' account can delete themselves
       // If 'false' only admin can delete accounts
       allow_deletions: boolean;
 
       // If 'true' anyone can edit their name
       // If 'false' only admin can
       allow_edit_name: boolean;
 
       // If 'true' anyone can edit their cashout account
       // If 'false' only admin can
       allow_edit_cashout_payto_uri: boolean;
 
       // Default debt limit for newly created accounts
       default_debit_threshold: Amount;
 
       // Currency used by this bank.
       currency: string;
 
       // How the bank SPA should render this currency.
       currency_specification: CurrencySpecification;
 
       // TAN channels supported by the server
       supported_tan_channels: TanChannel[];
 
       // Wire transfer type supported by the bank.
       // Defaults to 'iban' is missing
       // @since **v4**, will become mandatory in the next version.
       wire_type?: string;
 
       // Wire transfer execution fees. Only applies to bank transactions and withdrawals.
       // @since **v4**, will become mandatory in the next version.
       wire_transfer_fees?: Amount;
 
       // Minimum wire transfer amount allowed. Only applies to bank transactions and withdrawals.
       // @since **v4**, will become mandatory in the next version.
       min_wire_transfer_amount?: Amount;
 
       // Maximum wire transfer amount allowed. Only applies to bank transactions and withdrawals.
       // @since **v4**, will become mandatory in the next version.
       max_wire_transfer_amount?: Amount;
     }
 
 
 
 Authentication
 --------------
 
 Some endpoints requires the client to authenticate using a bearer token. Tokens can be obtained or refreshed using the ``/accounts/$USERNAME/token`` endpoint.
 This endpoint support authentication via HTTP Basic auth (RFC 7617). When using Basic authentication, the user-id must be the bank's username, and the password the password of the corresponding user.
 
 The user ``admin`` is a special, hard-coded username. Some requests require the client to authenticate as administrator.
 
 .. warning::
 
   Since **v7** Basic authentication for endpoints other than ``/accounts/$USERNAME/token`` has been deprecated and will no longer be supported in the next release.
 
 .. http:post:: /accounts/$USERNAME/token
 
   Create an authentification token.
 
   **Request:**
 
   .. ts:def:: TokenRequest
 
     interface TokenRequest {
       // Scope for the token.
       scope: "readonly" | "readwrite" | "revenue" | "wiregateway" | "observability";
 
       // Custom token validity duration
       duration?: RelativeTime;
 
       // Is the token refreshable into a new token during its
       // validity?
       // Refreshable tokens effectively provide indefinite
       // access if they are refreshed in time.
       refreshable?: boolean;
 
       // Optional token description
       // @since **v4**
       description?: string;
     }
 
   **Response:**
 
   :http:statuscode:`200 Ok`:
     Response is a `TokenSuccessResponse`.
   :http:statuscode:`202 Accepted`:
     2FA is required for this operation. This returns the `ChallengeResponse` response. @since **v10**
   :http:statuscode:`401 Unauthorized`:
     Invalid or missing credentials.
   :http:statuscode:`403 Forbidden`:
     * ``TALER_EC_GENERIC_FORBIDDEN``: missing rights.
     * ``TALER_EC_BANK_ACCOUNT_LOCKED``: account is locked and cannot create new token using its password.
 
   **Details:**
 
   .. ts:def:: TokenSuccessResponse
 
     interface TokenSuccessResponse {
       // Expiration determined by the server.
       // Can be based on the token_duration
       // from the request, but ultimately the
       // server decides the expiration.
       expiration: Timestamp;
 
       // Opque access token.
       access_token: string;
     }
 
 .. http:delete:: /accounts/$USERNAME/token
 
   Invalidate the access token that is being used to make the request.
 
   **Authentication:**  The client must authenticate with a valid access token.
 
   **Response:**
 
   :http:statuscode:`204 No content`:
     The token have been deleted.
   :http:statuscode:`401 Unauthorized`:
     Invalid or missing credentials.
   :http:statuscode:`403 Forbidden`:
     Missing rights.
 
 .. http:get:: /accounts/$USERNAME/tokens
 
   Retrieve a subset of tokens related to $USERNAME.
   @since **v4**
 
   **Request:**
 
   :query limit: *Optional.*
     At most return the given number of results. Negative for descending by ``token_id``, positive for ascending by ``token_id``. Defaults to ``-20``. Since **v5**.
   :query offset: *Optional.*
     Starting ``token_id`` for :ref:`pagination <row-id-pagination>`. Since **v5**.
   :query delta: *Optional.*
     Deprecated since **v5**. Use *limit* instead.
   :query start: *Optional.*
     Deprecated since **v5**. Use *offset* instead.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     Response is a `TokenInfos`.
   :http:statuscode:`204 No content`:
     No tokens.
   :http:statuscode:`401 Unauthorized`:
     Invalid or missing credentials.
   :http:statuscode:`403 Forbidden`:
     Mmissing rights.
 
   **Details:**
 
   .. ts:def:: TokenInfos
 
     interface TokenInfos {
       tokens: TokenInfo[];
     }
 
   .. ts:def:: TokenInfo
 
     interface TokenInfo {
       // Time when the token was created.
       creation_time: Timestamp;
 
       // Expiration determined by the server.
       // Can be based on the token_duration
       // from the request, but ultimately the
       // server decides the expiration.
       expiration: Timestamp;
 
       // Scope for the token.
       scope: "readonly" | "readwrite" | "revenue" | "wiregateway";
 
       // Is the token refreshable into a new token during its
       // validity?
       // Refreshable tokens effectively provide indefinite
       // access if they are refreshed in time.
       refreshable: boolean;
 
       // Optional token description
       description?: string;
 
       // Time when the token was last used.
       last_access: Timestamp;
 
       // ID identifying the token
       token_id: Integer;
 
       // deprecated since **v9**. Use *token_id* instead.
       row_id: Integer;
     }
 
 .. http:delete:: /accounts/$USERNAME/tokens/$TOKEN_ID
 
   Delete an access token.
 
   **Response:**
 
   :http:statuscode:`204 No content`:
     The token have been deleted.
   :http:statuscode:`404 Not found`:
     Token ``$TOKEN_ID`` was not found.
   :http:statuscode:`401 Unauthorized`:
     Invalid or missing credentials.
   :http:statuscode:`403 Forbidden`:
     Missing rights.
 
 Bank Web UI
 -----------
 
 The web UI for the bank is typically served under ``/``.
 
 
 Account Management
 ------------------
 
 .. _bank-account-register:
 
 .. http:post:: /accounts
 
   Create a new bank account.  Depending on the configuration,
   the account creation is self-serve, or only restricted to
   the administrators.
 
   **Request:**
 
   .. ts:def:: RegisterAccountRequest
 
     interface RegisterAccountRequest {
       // Username of the account
       // Must match [a-zA-Z0-9\-\._~]{1, 126}
       username: string;
 
       // Password of the account used for authentication
       password: string;
 
       // Legal name of the account owner
       name: string;
 
       // Make this account visible to anyone?
       // Defaults to false.
       is_public?: boolean;
 
       // Make this account a taler exchange account?
       // If true:
       // - incoming transactions to the account that do not
       //   have a valid reserve public key are automatically
       // - the account provides the taler-wire-gateway-api endpoints
       // Defaults to false.
       is_taler_exchange?: boolean;
 
       // Addresses where to send the TAN for protected operations.
       contact_data?: ChallengeContactData;
 
       // Payto URI of a fiat bank account.
       // Payments will be sent to this bank account
       // when the user wants to convert the regional currency
       // back to fiat currency outside bank.
       cashout_payto_uri?: string;
 
       // Simple payto URI of this bank account.
       // Used mostly for testing, this field is ignored if the bank payment
       // method is not IBAN.
       payto_uri?: string;
 
       // If present, set the max debit allowed for this user
       // Only admin can set this property.
       debit_threshold?: Amount;
 
       // If present, set the user conversion rate class
       // Only admin can set this property.
       // @since **v9**
       conversion_rate_class_id?: Integer;
 
       // @deprecated in **v10**
       // If present, enables 2FA and set the TAN channel used for challenges
       // Only admin can set this property, other user can reconfig their account
       // after creation.
       tan_channel?: TanChannel;
 
       // If present, enables 2FA and set the TAN channels used for challenges
       // Only admin can set this property, other user can reconfig their account
       // after creation.
       // @since **v10**
       tan_channels?: TanChannel[];
 
       // @deprecated in **v9**, use conversion_rate_class_id instead
       min_cashout?: Amount;
     }
 
   .. ts:def:: ChallengeContactData
 
     interface ChallengeContactData {
       // E-Mail address
       email?: EmailAddress;
 
       // Phone number.
       phone?: PhoneNumber;
     }
 
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     Response is a `RegisterAccountResponse`.
   :http:statuscode:`400 Bad request`:
     Input data was invalid.  For example, the client specified a invalid
     phone number or e-mail address.
   :http:statuscode:`401 Unauthorized`:
     Invalid or missing credentials.
   :http:statuscode:`403 Forbidden`:
     Missing rights.
   :http:statuscode:`409 Conflict`:
     * ``TALER_EC_BANK_REGISTER_USERNAME_REUSE`` : username already used.
     * ``TALER_EC_BANK_REGISTER_PAYTO_URI_REUSE`` : payto URI already used.
     * ``TALER_EC_BANK_UNALLOWED_DEBIT`` : admin account does not have sufficient funds to grant bonus.
     * ``TALER_EC_BANK_RESERVED_USERNAME_CONFLICT`` : a reserved username was attempted, like ``admin`` or ``bank``
     * ``TALER_EC_BANK_NON_ADMIN_PATCH_DEBT_LIMIT`` : a non-admin user has tried to create an account with a customer debt limit.
     * ``TALER_EC_BANK_NON_ADMIN_SET_CONVERSION_RATE_CLASS`` : a non-admin user has tried to create an account with a conversion rate class. Since **v9**
     * ``TALER_EC_BANK_NON_ADMIN_SET_TAN_CHANNEL`` : a non-admin user has tried to create an account with 2fa.
     * ``TALER_EC_BANK_TAN_CHANNEL_NOT_SUPPORTED``: ``tan_channel`` or one of ``tan_channels`` is not supported, check bank config to find supported ones.
     * ``TALER_EC_BANK_MISSING_TAN_INFO``: the user did not share any contact data where to send the TAN via ``tan_channel`` or one of ``tan_channels``.
     * ``TALER_EC_BANK_PASSWORD_TOO_SHORT``: password is shorter than 8 characters.
     * ``TALER_EC_BANK_PASSWORD_TOO_LONG``: password is longer than 64 characters.
     * ``TALER_EC_BANK_CONVERSION_RATE_CLASS_UNKNOWN`` : no conversion rate class found for this id. Since **v9**
 
   **Details:**
 
   .. ts:def:: RegisterAccountResponse
 
     interface RegisterAccountResponse {
       // Full payto URI of this bank account.
       internal_payto_uri: string;
     }
 
 .. _account-reconfig:
 
 .. http:patch:: /accounts/$USERNAME
 
   Allows reconfiguring the account data of ``$USERNAME``.
 
   **Request:**
 
   .. ts:def:: AccountReconfiguration
 
     interface AccountReconfiguration {
       // Addresses where to send the TAN for protected operations.
       contact_data?: ChallengeContactData;
 
       // Payto URI of a fiat bank account.
       // Payments will be sent to this bank account
       // when the user wants to convert the regional currency
       // back to fiat currency outside bank.
       // Only admin can change this property if not allowed in config
       // Sending null will disable cashout
       cashout_payto_uri?: string | null;
 
       // If present, change the legal name associated with $username.
       // Only admin can change this property if not allowed in config
       name?: string;
 
       // Make this account visible to anyone?
       is_public?: boolean;
 
       // If present, change the max debit allowed for this user
       // Only admin can change this property.
       debit_threshold?: Amount;
 
       // If present, set the user conversion rate class
       // Only admin can set this property.
       // Sending null will remove the class and switch to default class
       // @since **v9**
       conversion_rate_class_id?: Integer | null;
 
       // @deprecated in **v10**
       // If present, enables 2FA and set the TAN channel used for challenges
       // Sending null will disable 2FA
       tan_channel?: TanChannel | null;
 
       // If present and not empty, enables 2FA and set the TAN channels used for challenges
       // Sending null or an empty array will disable 2FA
       // @since **v10**
       tan_channels?: TanChannel[] | null;
 
       // @deprecated in **v9**, user conversion rate classes instead
       min_cashout?: Amount;
     }
 
   **Response:**
 
   :http:statuscode:`202 Accepted`:
     2FA is required for this operation. This returns the `ChallengeResponse` response. @since **v10**
   :http:statuscode:`204 No content`:
     Operation successful.
   :http:statuscode:`401 Unauthorized`:
     Invalid or missing credentials.
   :http:statuscode:`403 Forbidden`:
     Missing rights.
   :http:statuscode:`404 Not found`:
     The account pointed by ``$USERNAME`` was not found.
   :http:statuscode:`409 Conflict`:
     * ``TALER_EC_BANK_NON_ADMIN_PATCH_LEGAL_NAME`` : a non-admin user has tried to change their legal name.
     * ``TALER_EC_BANK_NON_ADMIN_PATCH_CASHOUT`` : a non-admin user has tried to change their cashout account.
     * ``TALER_EC_BANK_NON_ADMIN_PATCH_DEBT_LIMIT`` : a non-admin user has tried to change their debt limit.
     * ``TALER_EC_BANK_NON_ADMIN_SET_CONVERSION_RATE_CLASS`` : a non-admin user has tried to create an account with a conversion rate class. Since **v9**
     * ``TALER_EC_BANK_TAN_CHANNEL_NOT_SUPPORTED`` : ``tan_channel`` or one of ``tan_channels`` is not supported, check bank config to find supported ones.
     * ``TALER_EC_BANK_MISSING_TAN_INFO`` : the user did not share any contact data where to send the TAN via ``tan_channel`` or one of ``tan_channels``.
     * ``TALER_EC_BANK_CONVERSION_RATE_CLASS_UNKNOWN`` : no conversion rate class found for this id. Since **v9**
 
 
 .. _account-password-reconfig:
 
 .. http:patch:: /accounts/$USERNAME/auth
 
   Allows changing the account's password.
 
 
   **Request:**
 
   .. ts:def:: AccountPasswordChange
 
     interface AccountPasswordChange {
       // Old password. If present it need to match the current
       // password before updating.
       old_password?: string;
       // New password.
       new_password: string;
     }
 
   **Response:**
 
   :http:statuscode:`202 Accepted`:
     2FA is required for this operation. This returns the `ChallengeResponse` response. @since **v10**
   :http:statuscode:`204 No content`:
     Operation successful.
   :http:statuscode:`404 Not found`:
     The account pointed by ``$USERNAME`` was not found.
   :http:statuscode:`401 Unauthorized`:
     Invalid or missing credentials.
   :http:statuscode:`403 Forbidden`:
     Missing rights.
   :http:statuscode:`409 Conflict`:
     * ``TALER_EC_BANK_NON_ADMIN_PATCH_MISSING_OLD_PASSWORD``: a non-admin user has tried to change their password whihout providing the current one.
     * ``TALER_EC_BANK_PATCH_BAD_OLD_PASSWORD`` : provided old password does not match current password.
     * ``TALER_EC_BANK_PASSWORD_TOO_SHORT``: new password is shorter than 8 characters.
     * ``TALER_EC_BANK_PASSWORD_TOO_LONG``: new password is longer than 64 characters.
 
 
 .. _delete-account:
 
 .. http:delete:: /accounts/$USERNAME
 
   Delete the account whose username is ``$USERNAME``.  The deletion
   succeeds only if the balance is *zero*.  Typically only available to
   the administrator, but can be configured to allow ordinary users too.
 
   **Response:**
 
   :http:statuscode:`202 Accepted`:
     2FA is required for this operation. This returns the `ChallengeResponse` response. @since **v10**
   :http:statuscode:`204 No content`:
     The account was successfully deleted.
   :http:statuscode:`401 Unauthorized`:
     Invalid or missing credentials.
   :http:statuscode:`403 Forbidden`:
     Missing rights.
   :http:statuscode:`404 Not found`:
     The account pointed by ``$USERNAME`` was not found.
   :http:statuscode:`409 Conflict`:
     * ``TALER_EC_BANK_RESERVED_USERNAME_CONFLICT`` : a reserved username was attempted, like ``admin`` or ``bank``.
     * ``TALER_EC_BANK_ACCOUNT_BALANCE_NOT_ZERO``: the account balance was not zero.
 
 .. _account-list:
 
 .. http:get:: /public-accounts
 
   Show those accounts whose histories are publicly visible.  For example,
   accounts from donation receivers.  As such, this request is unauthenticated.
 
   **Request:**
 
   :query limit: *Optional.*
     At most return the given number of results. Negative for descending by ``row_id``, positive for ascending by ``row_id``. Defaults to ``-20``. Since **v5**.
   :query offset: *Optional.*
     Starting ``row_id`` for :ref:`pagination <row-id-pagination>`. Since **v5**.
   :query filter_name: *Optional.*
     Pattern to filter on the account's 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.
   :query delta: *Optional.*
     Deprecated since **v5**. Use *limit* instead.
   :query start: *Optional.*
     Deprecated since **v5**. Use *offset* instead.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     Response is a `PublicAccountsResponse`.
   :http:statuscode:`204 No content`:
     No public account.
 
   **Details:**
 
   .. ts:def:: PublicAccountsResponse
 
     interface PublicAccountsResponse {
       public_accounts: PublicAccount[];
     }
 
   .. ts:def:: PublicAccount
 
     interface PublicAccount {
       // Username of the account
       username: string;
 
       // Full payto URI of this bank account.
       payto_uri: string;
 
       // Current balance of the account
       balance: Balance;
 
       // Is this a taler exchange account?
       is_taler_exchange: boolean;
 
       // Opaque unique ID used for pagination.
       // @since **v4**, will become mandatory in the next version.
       row_id?: Integer;
     }
 
 .. 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.
   This request is only available to the administrator.
 
   **Request:**
 
   :query limit: *Optional.*
     At most return the given number of results. Negative for descending by ``row_id``, positive for ascending by ``row_id``. Defaults to ``-20``. Since **v5**.
   :query offset: *Optional.*
     Starting ``row_id`` for :ref:`pagination <row-id-pagination>`. Since **v5**.
   :query filter_name: *Optional.*
     Pattern to filter on the account's legal name.  Given
     the filter 'foo', all the accounts will **contain**
     'foo' in their legal name.  Without this option,
     all the existing accounts are returned.
   :query conversion_rate_class_id: *Optional.*
     Id of a conversion rate class. Given the filter '1', the accounts will be part of the conversion rate class 1. Given the filter '0', will have no conversion rate class. Without this option all the existing accounts are returned. Since **v9**.
   :query delta: *Optional.*
     Deprecated since **v5**. Use *limit* instead.
   :query start: *Optional.*
     Deprecated since **v5**. Use *offset* instead.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     At least one account was found.
     The server responds with a `ListBankAccountsResponse` object.
   :http:statuscode:`204 No Content`:
     No accounts were found for the given request.
   :http:statuscode:`401 Unauthorized`:
     Invalid or missing credentials.
   :http:statuscode:`403 Forbidden`:
     Missing rights.
 
   **Details:**
 
   .. ts:def:: ListBankAccountsResponse
 
     interface ListBankAccountsResponse {
       accounts: AccountMinimalData[];
     }
 
   .. ts:def:: Balance
 
     interface Balance {
       amount: Amount;
       credit_debit_indicator: "credit" | "debit";
     }
 
   .. ts:def:: AccountMinimalData
 
     interface AccountMinimalData {
       // Username of the account
       username: string;
 
       // Legal name of the account owner.
       name: string;
 
       // Full payto URI of this bank account.
       payto_uri: string;
 
       // Current balance of the account
       balance: Balance;
 
       // Number indicating the max debit allowed for the requesting user.
       debit_threshold: Amount;
 
       // Custom minimum cashout amount for this account.
       // If null or absent, the global conversion fee is used.
       // @since **v6**
       // @deprecated in **v9**, use conversion_rate_class_id instead
       min_cashout?: Amount;
 
       // Is this account visible to anyone?
       is_public: boolean;
 
       // Is this a taler exchange account?
       is_taler_exchange: boolean;
 
       // Is the account locked.
       // Defaults to false.
       // @deprecated since **v7**
       is_locked?: boolean;
 
       // Opaque unique ID used for pagination.
       // @since **v4**, will become mandatory in the next version.
       row_id?: Integer;
 
       // Current status of the account
       // active: the account can be used
       // locked: the account can be used but cannot create new tokens
       // @since **v7**
       // deleted: the account has been deleted but is retained for compliance
       // reasons, only the administrator can access it
       // Defaults to 'active' is missing
       // @since **v4**, will become mandatory in the next version.
       status?: "active" | "locked" | "deleted";
 
       // Conversion rate class of the user
       // Only present if conversion is activated on the server
       // @since **v9**
       conversion_rate_class_id?: Integer;
 
       // Conversion rate available to the user
       // Only present if conversion is activated on the server
       // @since **v9**
       conversion_rate?: ConversionRate;
     }
 
 .. _bank-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:**
 
   :http:statuscode:`200 OK`:
     The bank responds with an `AccountData` object.
   :http:statuscode:`401 Unauthorized`:
     Invalid or missing credentials.
   :http:statuscode:`403 Forbidden`:
     Missing rights.
   :http:statuscode:`404 Not found`:
     The account pointed by ``$USERNAME`` was not found.
 
   **Details:**
 
   .. ts:def:: AccountData
 
     interface AccountData {
       // Legal name of the account owner.
       name: string;
 
       // Available balance on the account.
       balance: Balance;
 
       // Full payto URI of the account.
       payto_uri: string;
 
       // Number indicating the max debit allowed for the requesting user.
       debit_threshold: Amount;
 
       // Custom minimum cashout amount for this account.
       // If null or absent, the global conversion fee is used.
       // @since **v6**
       // @deprecated in **v9**, use conversion_rate_class_id instead
       min_cashout?: Amount;
 
       // Addresses where to send the TAN for transactions.
       // Currently only used for cashouts.
       // If missing, cashouts will fail.
       // In the future, might be used for other transactions
       // as well.
       contact_data?: ChallengeContactData;
 
       // Full 'payto' URI of a fiat bank account where to send cashouts with
       // ``name`` as the 'receiver-name'.
       // 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_payto_uri?: string;
 
       // Is this account visible to anyone?
       is_public: boolean;
 
       // Is this a taler exchange account?
       is_taler_exchange: boolean;
 
       // Is the account locked.
       // Defaults to false.
       // @deprecated since **v7**
       is_locked?: boolean;
 
       // @deprecated in **v10**
       // Is 2FA enabled and what channel is used for challenges?
       tan_channel?: TanChannel;
 
       // Is 2FA enabled and what channels are used for challenges?
       // @since **v10**
       tan_channels?: TanChannel[];
 
       // Current status of the account
       // active: the account can be used
       // locked: the account can be used but cannot create new tokens
       // @since **v7**
       // deleted: the account has been deleted but is retained for compliance
       // reasons, only the administrator can access it
       // Defaults to 'active' is missing
       // @since **v4**, will become mandatory in the next version.
       status?: "active" | "locked" | "deleted";
 
       // Conversion rate class of the user
       // Only present if conversion is activated on the server
       // @since **v9**
       conversion_rate_class_id?: Integer;
     }
 
 Transactions
 ------------
 
 .. http:get:: /accounts/$USERNAME/transactions
 
   Retrieve a subset of transactions related to $USERNAME.
 
   **Request:**
 
   :query limit: *Optional.*
     At most return the given number of results. Negative for descending by ``row_id``, positive for ascending by ``row_id``. Defaults to ``-20``. Since **v5**.
   :query offset: *Optional.*
     Starting ``row_id`` for :ref:`pagination <row-id-pagination>`. Since **v5**.
   :query timeout_ms: *Optional.*
     Timeout in milliseconds, for :ref:`long-polling <long-polling>`, to wait for at least one element to be shown. Only useful if *limit* is positive. Since protocol **v5**.
   :query delta: *Optional.*
     Deprecated since **v5**. Use *limit* instead.
   :query start: *Optional.*
     Deprecated since **v5**. Use *offset* instead.
   :query long_poll_ms: *Optional.*
     Deprecated since **v5**. Use *timeout_ms* instead.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The bank responds with an `BankAccountTransactionsResponse` object.
   :http:statuscode:`204 No content`:
     No transaction found.
   :http:statuscode:`401 Unauthorized`:
     Invalid or missing credentials.
   :http:statuscode:`403 Forbidden`:
     Missing rights.
   :http:statuscode:`404 Not found`:
     The account pointed by ``$USERNAME`` was not found.
 
   **Details:**
 
   .. ts:def:: BankAccountTransactionsResponse
 
     interface BankAccountTransactionsResponse {
       transactions: BankAccountTransactionInfo[];
     }
 
 .. http:get:: /accounts/$USERNAME/transactions/$TRANSACTION_ID
 
   Retrieve the transaction whose identifier is ``TRANSACTION_ID``.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The bank responds with an `BankAccountTransactionInfo` object.
   :http:statuscode:`401 Unauthorized`:
     Invalid or missing credentials.
   :http:statuscode:`403 Forbidden`:
     Missing rights.
   :http:statuscode:`404 Not found`:
     The account pointed by ``$USERNAME`` was not found.
 
   **Details:**
 
   .. ts:def:: BankAccountTransactionInfo
 
     interface BankAccountTransactionInfo {
       // Full payto URI to identify the receiver of funds.
       creditor_payto_uri: string;
 
       // Full payto URI to identify the sender of funds.
       debtor_payto_uri: string;
 
       // Amount received.
       amount: Amount;
 
       // The direction of the transaction relative to $USERNAME account.
       // debit: $USERNAME is the debtor
       // credit: $USERNAME is the creditor
       direction: "debit" | "credit";
 
       // The wire transfer subjec
       subject: string;
 
       // Transaction unique ID.  Matches
       // $TRANSACTION_ID from the URI.
       row_id: Integer;
 
       // Date of the transaction.
       date: Timestamp;
     }
 
 .. http:post:: /accounts/$USERNAME/transactions
 
   Create a new transaction where the bank account with the label ``USERNAME`` is **debited**.
 
   **Request:**
 
   .. ts:def:: CreateTransactionRequest
 
     interface CreateTransactionRequest {
       // 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;
 
       // Nonce to make the request idempotent.  Requests with the same
       // ``request_uid`` that differ in any of the other fields
       // are rejected.
       // @since **v4**, will become mandatory in the next version.
       request_uid?: ShortHashCode;
     }
 
   **Response:**
 
   :http:statuscode:`200 Ok`:
     The bank responds with an `CreateTransactionResponse` object.
   :http:statuscode:`202 Accepted`:
     2FA is required for this operation. This returns the `ChallengeResponse` response. @since **v10**
   :http:statuscode:`400 Bad Request`:
     The request was invalid or the payto://-URI used unacceptable features.
   :http:statuscode:`401 Unauthorized`:
     Invalid or missing credentials.
   :http:statuscode:`403 Forbidden`:
     Missing rights.
   :http:statuscode:`404 Not found`:
     The account pointed by ``$USERNAME`` was not found.
   :http:statuscode:`409 Conflict`:
     * ``TALER_EC_BANK_SAME_ACCOUNT`` : creditor account is the same than ``USERNAME``.
     * ``TALER_EC_BANK_UNKNOWN_CREDITOR`` : creditor account was not found.
     * ``TALER_EC_BANK_UNALLOWED_DEBIT`` : the account does not have sufficient funds or the amount is too low or too high.
     * ``TALER_EC_BANK_TRANSFER_REQUEST_UID_REUSED``: an operation with the same ``request_uid`` but different details has been submitted before.
 
   **Details:**
 
   .. ts:def:: CreateTransactionResponse
 
     interface CreateTransactionResponse {
       // ID identifying the transaction being created
       row_id: Integer;
     }
 
 Account withdrawals
 -------------------
 
 .. http:post:: /accounts/$USERNAME/withdrawals
 
   Create a withdrawal operation, resulting in a ``taler://withdraw`` URI.
 
   **Request:**
 
   The request must be a `BankAccountCreateWithdrawalRequest`.
 
   **Response:**
 
   :http:statuscode:`200 Ok`:
     The bank responds with an `BankAccountCreateWithdrawalResponse` object.
   :http:statuscode:`401 Unauthorized`:
     Invalid or missing credentials.
   :http:statuscode:`403 Forbidden`:
     Missing rights.
   :http:statuscode:`404 Not found`:
     The account pointed by ``$USERNAME`` was not found.
   :http:statuscode:`409 Conflict`:
     The account does not have sufficient funds.
 
   **Details:**
 
   .. ts:def:: BankAccountCreateWithdrawalRequest
 
     interface BankAccountCreateWithdrawalRequest {
       // Amount to withdraw.  If given, the wallet
       // cannot change the amount.
       // Optional since **v6**.
       amount?: Amount;
 
       // Suggested amount to withdraw. The wallet can
       // still change the suggestion.
       // @since **v6**
       suggested_amount?: Amount;
 
       // If true, tell the wallet not to allow the user to
       // specify an amount to withdraw and to not provide
       // any amount when registering with the withdrawal
       // operation. The amount to withdraw will be set
       // by the final ``/withdrawals/$WITHDRAWAL_ID/confirm`` step.
       // @since **v8**
       no_amount_to_wallet?: boolean;
     }
 
   .. ts:def:: BankAccountCreateWithdrawalResponse
 
     interface BankAccountCreateWithdrawalResponse {
       // ID identifying the operation being created
       withdrawal_id: string;
 
       // URI that can be passed to the wallet to initiate the withdrawal
       taler_withdraw_uri: string;
     }
 
 .. http:post:: /accounts/$USERNAME/withdrawals/$WITHDRAWAL_ID/confirm
 
   Confirms ``WITHDRAWAL_ID`` operation.  Has no effect on an already confirmed
   withdrawal operation.  This call is responsible for wiring the funds to the
   exchange.
 
   **Request:**
 
   .. ts:def:: BankAccountConfirmWithdrawalRequest
 
     interface BankAccountConfirmWithdrawalRequest {
 
       // Selected amount to be transferred. Optional if the
       // backend already knows the amount.
       // @since **v6**
       amount?: Amount;
     }
 
 
   **Response:**
 
   :http:statuscode:`202 Accepted`:
     2FA is required for this operation. This returns the `ChallengeResponse` response. @since **v10**
   :http:statuscode:`204 No content`:
     The withdrawal operation has been confirmed.
   :http:statuscode:`401 Unauthorized`:
     Invalid or missing credentials.
   :http:statuscode:`403 Forbidden`:
     Missing rights.
   :http:statuscode:`404 Not found`:
     The operation was not found.
   :http:statuscode:`409 Conflict`:
     * ``TALER_EC_BANK_CONFIRM_ABORT_CONFLICT`` : the withdrawal has been aborted previously and can't be confirmed.
     * ``TALER_EC_BANK_CONFIRM_INCOMPLETE`` : the withdraw operation cannot be confirmed because no exchange and reserve public key selection happened before.
     * ``TALER_EC_BANK_UNALLOWED_DEBIT`` : the account does not have sufficient funds or the amount is too low or too high.
     * ``TALER_EC_BANK_AMOUNT_DIFFERS`` : the specified amount will not work for this withdrawal (since **v6**).
     * ``TALER_EC_BANK_AMOUNT_REQUIRED`` : the backend requires an amount to be specified  (since **v6**).
 
 .. http:post:: /accounts/$USERNAME/withdrawals/$WITHDRAWAL_ID/abort
 
   Aborts ``WITHDRAWAL_ID`` operation.  Has no effect on an already aborted
   operation.
 
   **Response:**
 
   :http:statuscode:`204 No content`:
     The withdrawal operation has been aborted.
   :http:statuscode:`401 Unauthorized`:
     Invalid or missing credentials.
   :http:statuscode:`403 Forbidden`:
     Missing rights.
   :http:statuscode:`404 Not found`:
     The withdrawal operation was not found.
   :http:statuscode:`409 Conflict`:
     The withdrawal operation has been confirmed previously and can't be aborted.
 
 .. http:get:: /withdrawals/$WITHDRAWAL_ID
 
   Retrieve public information about ``WITHDRAWAL_ID`` withdrawal operation.
   Does not require further authentication as knowledge of ``WITHDRAWAL_ID``
   serves as an authenticator.
 
   **Request:**
 
   :query old_state:
     *Optional.* Defaults to "pending".
   :query timeout_ms: *Optional.*
     Timeout in milliseconds, for :ref:`long-polling <long-polling>`, to wait for the operation state to be different from *old_state*. Since **v5**.
   :query long_poll_ms: *Optional.*
     Deprecated since **v5.** Use *timeout_ms* instead.
 
   **Response:**
 
   :http:statuscode:`200 Ok`:
     The bank responds with an `WithdrawalPublicInfo` object.
   :http:statuscode:`404 Not found`:
     The operation was not found.
 
   **Details:**
 
   .. ts:def:: WithdrawalPublicInfo
 
     interface WithdrawalPublicInfo {
       // Current status of the operation
       // pending: the operation is pending parameters selection (exchange and reserve public key)
       // selected: the operations has been selected and is pending confirmation
       // aborted: the operation has been aborted
       // confirmed: the transfer has been confirmed and registered by the bank
       status: "pending" | "selected" | "aborted" | "confirmed";
 
       // Amount that will be withdrawn with this operation
       // (raw amount without fee considerations).  Only
       // given once the amount is fixed and cannot be changed.
       // Optional since **v6**.
       amount?: Amount;
 
       // Suggestion for the amount to be withdrawn with this
       // operation.  Given if a suggestion was made but the
       // user may still change the amount.
       // Optional since **v6**.
       suggested_amount?: Amount;
 
       // If true, the wallet must not allow the user to
       // specify an amount to withdraw and to not provide
       // any amount when registering with the withdrawal
       // operation. The amount to withdraw will be set
       // by the final ``/withdrawals/$WITHDRAWAL_ID/confirm`` step.
       // @since **v8**
       no_amount_to_wallet?: boolean;
 
       // Account username
       username: string;
 
       // Reserve public key selected by the exchange,
       // only non-null if ``status`` is ``selected`` or ``confirmed``.
       selected_reserve_pub?: string;
 
       // Exchange account selected by the wallet
       // only non-null if ``status`` is ``selected`` or ``confirmed``.
       selected_exchange_account?: string;
     }
 
 Cashouts
 --------
 
 .. _account-cashout:
 
 .. http:post:: /accounts/$USERNAME/cashouts
 
   Initiates a conversion to fiat currency.  The fiat
   bank account to be
   credited is the one specified at registration time via the
   *cashout_payto_uri* parameter.  The regional bank account
   is specified via ``$USERNAME``.
 
   .. note::
 
     Consult the `cashout rates call <cashout-rates_>`_ to learn
     about any applicable fee or exchange rate.
 
 
   **Request:**
 
   .. ts:def:: CashoutRequest
 
     interface CashoutRequest {
       // Nonce to make the request idempotent.  Requests with the same
       // ``request_uid`` that differ in any of the other fields
       // are rejected.
       request_uid: ShortHashCode;
 
       // Optional subject to associate to the
       // cashout operation.  This data will appear
       // as the incoming wire transfer subject in
       // the user's fiat bank account.
       subject?: string;
 
       // That is the plain amount that the user specified
       // to cashout.  Its $currency is the (regional) currency of the
       // bank instance.
       amount_debit: Amount;
 
       // That is the amount that will effectively be
       // transferred by the bank to the user's fiat bank
       // account.
       // It is expressed in the fiat currency and
       // is calculated after the cashout fee and the
       // exchange rate.  See the /cashout-rate call.
       // The client needs to calculate this amount
       // correctly based on the amount_debit and the cashout rate,
       // otherwise the request will fail.
       amount_credit: Amount;
     }
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The cashout request was correctly created.
     This returns the `CashoutResponse` response.
   :http:statuscode:`202 Accepted`:
     2FA is required for this operation. This returns the `ChallengeResponse` response. @since **v10**
   :http:statuscode:`401 Unauthorized`:
     Invalid or missing credentials.
   :http:statuscode:`403 Forbidden`:
     Missing rights.
   :http:statuscode:`404 Not found`:
     The account pointed by ``$USERNAME`` was not found.
   :http:statuscode:`409 Conflict`:
     * ``TALER_EC_BANK_TRANSFER_REQUEST_UID_REUSED``: an operation with the same ``request_uid`` but different details has been submitted before.
     * ``TALER_EC_BANK_BAD_CONVERSION``: exchange rate was calculated incorrectly by the client.
     * ``TALER_EC_BANK_BANK_CONVERSION_AMOUNT_TO_SMALL``: the amount of the cashout is too small.
     * ``TALER_EC_BANK_UNALLOWED_DEBIT``: the account does not have sufficient funds or the amount is too low or too high.
     * ``TALER_EC_BANK_CONFIRM_INCOMPLETE``: the user did not share any cashout payto to uri where to wire funds.
   :http:statuscode:`501 Not Implemented`:
     * ``TALER_EC_BANK_TAN_CHANNEL_NOT_SUPPORTED``: the chosen ``tan_channel`` or one of ``tan_channels`` is not currently supported.
     * This server does not support conversion, client should check config response.
 
   **Details:**
 
   .. ts:def:: CashoutResponse
 
     interface CashoutResponse {
       // ID identifying the operation being created
       cashout_id: Integer;
     }
 
 .. _circuit-cashout-details:
 
 .. http:get:: /accounts/$USERNAME/cashouts/$CASHOUT_ID
 
   Returns information about the status of the ``$CASHOUT_ID`` operation.
   The request is available to the administrator and the account owner.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     Response is a `CashoutStatusResponse`.
   :http:statuscode:`401 Unauthorized`:
     Invalid or missing credentials.
   :http:statuscode:`403 Forbidden`:
     Missing rights.
   :http:statuscode:`404 Not found`:
     The cashout operation was not found.
   :http:statuscode:`501 Not implemented`:
     This server does not support conversion, client should check config response.
 
   **Details:**
 
   .. ts:def:: CashoutStatusResponse
 
     interface CashoutStatusResponse {
       // Amount debited to the regional bank account.
       amount_debit: Amount;
 
       // Amount credited to the fiat bank account.
       amount_credit: Amount;
 
       // Transaction subject.
       subject: string;
 
       // Time when the cashout was created.
       creation_time: Timestamp;
     }
 
 .. _circuit-cashouts:
 
 .. http:get:: /accounts/$USERNAME/cashouts
 
   Returns the list of all cash-out operations for an account.
 
   **Request:**
 
   :query limit: *Optional.*
     At most return the given number of results. Negative for descending by ``cashout_id``, positive for ascending by ``cashout_id``. Defaults to ``-20``. Since **v5**.
   :query offset: *Optional.*
     Starting ``cashout_id`` for :ref:`pagination <row-id-pagination>`. Since **v5**.
   :query delta: *Optional.*
     Deprecated since **v5**. Use *limit* instead.
   :query start: *Optional.*
     Deprecated since **v5**. Use *offset* instead.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     Response is a `Cashouts`.
   :http:statuscode:`204 No Content`:
     No cash-out operations were found.
   :http:statuscode:`401 Unauthorized`:
     Invalid or missing credentials.
   :http:statuscode:`403 Forbidden`:
     Missing rights.
   :http:statuscode:`501 Not implemented`:
     This server does not support conversion, client should check config response.
 
   **Details:**
 
   .. ts:def:: Cashouts
 
     interface Cashouts {
       // Every string represents a cash-out operation ID.
       cashouts: CashoutInfo[];
     }
 
   .. ts:def:: CashoutInfo
 
     interface CashoutInfo {
       cashout_id: Integer;
     }
 
 .. http:get:: /cashouts
 
   Returns the list of all cash-out operations for **all** accounts.
 
   Can only be used by the administrators.
 
   **Request:**
 
   :query limit: *Optional.*
     At most return the given number of results. Negative for descending by ``cashout_id``, positive for ascending by ``cashout_id``. Defaults to ``-20``. Since **v5**.
   :query offset: *Optional.*
     Starting ``cashout_id`` for :ref:`pagination <row-id-pagination>`. Since **v5**.
   :query delta: *Optional.*
     Deprecated since **v5**. Use *limit* instead.
   :query start: *Optional.*
     Deprecated since **v5**. Use *offset* instead.
 
   .. note::
 
     We might want to add a filter in the future to only
     query pending cashout operations.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     Response is a `GlobalCashouts`.
   :http:statuscode:`204 No Content`:
     No cash-out operations were found.
   :http:statuscode:`401 Unauthorized`:
     Invalid or missing credentials.
   :http:statuscode:`403 Forbidden`:
     Missing rights.
   :http:statuscode:`501 Not implemented`:
     This server does not support conversion, client should check config response.
 
   **Details:**
 
   .. ts:def:: GlobalCashouts
 
     interface GlobalCashouts {
       cashouts: GlobalCashoutInfo[];
     }
 
   .. ts:def:: GlobalCashoutInfo
 
     interface GlobalCashoutInfo {
       cashout_id: Integer;
       username: string;
     }
 
 Conversion rate class
 ---------------------
 
 .. http:post:: /conversion-rate-classes
 
   Create a new conversion rate classe.
 
   Only available to the administrator.
 
   Since protocol **v9**.
 
   **Request:**
 
   .. ts:def:: ConversionRateClassInput
 
     interface ConversionRateClassInput {
       // The name of this class
       name: string;
 
       // A description of the class
       description?: string;
 
       // Minimum fiat amount authorised for cashin before conversion
       cashin_min_amount?: Amount;
 
       // Exchange rate to buy regional currency from fiat
       cashin_ratio?: DecimalNumber;
 
       // Regional amount fee to subtract after applying the cashin ratio.
       cashin_fee?: Amount;
 
       // Rounding mode used during cashin conversion
       cashin_rounding_mode?: "zero" | "up" | "nearest";
 
       // Minimum regional amount authorised for cashout before conversion
       cashout_min_amount?: Amount;
 
       // Exchange rate to sell regional currency for fiat
       cashout_ratio?: DecimalNumber;
 
       // Fiat amount fee to subtract after applying the cashout ratio.
       cashout_fee?: Amount;
 
       // Rounding mode used during cashout conversion
       cashout_rounding_mode?: "zero" | "up" | "nearest";
     }
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The conversion rate class request was correctly created.
     This returns the `ConversionRateClassResponse` response.
   :http:statuscode:`401 Unauthorized`:
     Invalid or missing credentials.
   :http:statuscode:`403 Forbidden`:
     Missing rights.
   :http:statuscode:`409 Conflict`:
     * ``TALER_EC_BANK_NAME_REUSE`` : name already used.
   :http:statuscode:`501 Not implemented`:
     This server does not support conversion, client should check config response.
 
   **Details:**
 
   .. ts:def:: ConversionRateClassResponse
 
     interface ConversionRateClassResponse {
       // ID identifying the conversion rate class being created
       conversion_rate_class_id: Integer;
     }
 
 .. http:patch:: /conversion-rate-classes/{CLASS_ID}
 
   Edit an existing conversion rate class.
 
   Only available to the administrator.
 
   Since protocol **v9**.
 
   **Request:**
 
   `ConversionRateClassInput`
 
   **Response:**
 
   :http:statuscode:`204 No Content`:
     The conversion rate class request was correctly edited.
   :http:statuscode:`401 Unauthorized`:
     Invalid or missing credentials.
   :http:statuscode:`403 Forbidden`:
     Missing rights.
   :http:statuscode:`404 Not Found`:
     The conversion rate class was not found.
   :http:statuscode:`409 Conflict`:
     * ``TALER_EC_BANK_NAME_REUSE`` : name already used.
   :http:statuscode:`501 Not implemented`:
     This server does not support conversion, client should check config response.
 
 .. http:delete:: /conversion-rate-classes/{CLASS_ID}
 
   Delete an existing conversion rate class.
 
   Only available to the administrator.
 
   Since protocol **v9**.
 
   **Response:**
 
   :http:statuscode:`204 No Content`:
     The conversion rate class request was correctly deleted.
   :http:statuscode:`401 Unauthorized`:
     Invalid or missing credentials.
   :http:statuscode:`403 Forbidden`:
     Missing rights.
   :http:statuscode:`404 Not Found`:
     The conversion rate class was not found.
   :http:statuscode:`409 Conflict`:
     * ``TODO_LINKED_ACCOUNT`` : some accounts belongs to this class.
   :http:statuscode:`501 Not implemented`:
     This server does not support conversion, client should check config response.
 
 .. http:get:: /conversion-rate-classes/{CLASS_ID}
 
   Get an existing conversion rate class.
 
   Only available to the administrator.
 
   Since protocol **v9**.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     Response is a `ConversionRateClass`.
   :http:statuscode:`401 Unauthorized`:
     Invalid or missing credentials.
   :http:statuscode:`403 Forbidden`:
     Missing rights.
   :http:statuscode:`404 Not Found`:
     The conversion rate class was not found.
   :http:statuscode:`501 Not implemented`:
     This server does not support conversion, client should check config response.
 
   **Details:**
 
   .. ts:def:: ConversionRateClassResponse
 
     interface ConversionRateClass {
       // The name of this class
       name: string;
 
       // A description of the class
       description?: string;
 
       // Class unique ID
       conversion_rate_class_id: Integer;
 
       // Number of users affected to this class
       num_users: Integer;
 
       // Minimum fiat amount authorised for cashin before conversion
       cashin_min_amount?: Amount;
 
       // Exchange rate to buy regional currency from fiat
       cashin_ratio?: DecimalNumber;
 
       // Regional amount fee to subtract after applying the cashin ratio.
       cashin_fee?: Amount;
 
       // Rounding mode used during cashin conversion
       cashin_rounding_mode?: "zero" | "up" | "nearest";
 
       // Minimum regional amount authorised for cashout before conversion
       cashout_min_amount?: Amount;
 
       // Exchange rate to sell regional currency for fiat
       cashout_ratio?: DecimalNumber;
 
       // Fiat amount fee to subtract after applying the cashout ratio.
       cashout_fee?: Amount;
 
       // Rounding mode used during cashout conversion
       cashout_rounding_mode?: "zero" | "up" | "nearest";
     }
 
 .. http:get:: /conversion-rate-classes
 
   Returns the list of all conversion rate classes.
 
   Only available to the administrator.
 
   Since protocol **v9**.
 
   **Request:**
 
   :query limit: *Optional.*
     At most return the given number of results. Negative for descending by ``conversion_rate_class_id``, positive for ascending by ``conversion_rate_class_id``. Defaults to ``-20``.
   :query offset: *Optional.*
     Starting ``conversion_rate_class_id`` for :ref:`pagination <row-id-pagination>`.
   :query filter_name: *Optional.*
     Pattern to filter on the class name.  Given
     the filter 'foo', all the classes will **contain**
     'foo' in their name.  Without this option,
     all the existing classes are returned.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     Response is a `ConversionRateClasses`.
   :http:statuscode:`401 Unauthorized`:
     Invalid or missing credentials.
   :http:statuscode:`403 Forbidden`:
     Missing rights.
   :http:statuscode:`404 Not Found`:
     The conversion rate class was not found.
   :http:statuscode:`501 Not implemented`:
     This server does not support conversion, client should check config response.
 
   **Details:**
 
   .. ts:def:: ConversionRateClasses
 
     interface ConversionRateClasses {
       classes: ConversionRateClass[];
     }
 
 
 Two Factor Auth
 ---------------
 
 202 Challenge Responses
 ^^^^^^^^^^^^^^^^^^^^^^^
 
 Various APIs generate ``202 Accepted`` HTTP status codes when multi-factor
 authentication (MFA) is required.  In this case, the response will be a
 `ChallengeResponse`.  In these cases, the client must first request and solve
 one or more challenges before repeating the request. When repeating the
 request, they must include a list of comma-separated challenge IDs of the
 solved challenges in an ``Taler-Challenge-Ids`` HTTP header. The body must
 remain absolutely unchanged.
 
 .. note::
 
   If all allowed attempts to solve the MFA challenge(s) fail, the endpoint
   may start to return ``403 Forbidden`` until the issued challenges expire,
   preventing the request from being completed for a while.  In this case,
   repeating the request with a different body may still be allowed!
 
 .. ts:def:: ChallengeResponse
 
   // @since v10
   interface ChallengeResponse {
     // List of challenge IDs that must be solved before the
     // client may proceed.
     challenges: Challenge[];
 
     // True if **all** challenges must be solved (AND), false if
     // it is sufficient to solve one of them (OR).
     combi_and: boolean;
   }
 
 .. ts:def:: Challenge
 
   // @since v10
   interface Challenge {
     // Unique identifier of the challenge to solve to run this protected
     // operation.
     challenge_id: string;
 
     // Channel that will be used to transmit the challenge.
     tan_channel: TanChannel;
 
     // Hint to show to the user as to where the challenge will be
     // sent or what to use to solve the challenge. May not
     // contain the full address for privacy.
     tan_info: string;
   }
 
 .. ts:def:: TanChannel
 
   enum TanChannel {
     SMS = "sms",
     EMAIL = "email"
   }
 
 Requesting challenges
 ^^^^^^^^^^^^^^^^^^^^^
 
 .. http:post:: /accounts/$USERNAME/challenge/$CHALLENGE_ID
 
   Send TAN code for the ``CHALLENGE_ID`` challenge.
 
   This request can be posted several times to trigger TAN retransmission when the current code has expired or too many confirmation attempts have been made.
 
   This endpoint is not authenticated. @since **v10**
 
   **Request:**
 
   The request body must be empty.
 
   **Response:**
 
   :http:statuscode:`200 Ok`:
     The TAN code has been sent. The body will be a `ChallengeRequestResponse`.
   :http:statuscode:`404 Not Found`:
     * ``TALER_EC_BANK_TAN_CHANNEL_SCRIPT_FAILED``: TAN transmition failed.
     * ``TALER_EC_BANK_TAN_CHALLENGE_EXPIRED``: TAN transmition failed.
     The challenge was not found.
   :http:statuscode:`410 Gone`:
     The challenge was already solved.
   :http:statuscode:`429 Too many requests`:
     Too many challenges are active right now, you must wait or confirm current challenges.
   :http:statuscode:`502 Bad Gateway`:
     * ``TALER_EC_BANK_TAN_CHANNEL_SCRIPT_FAILED``: TAN transmition failed.
 
   **Details:**
 
   .. ts:def:: ChallengeRequestResponse
 
     interface ChallengeRequestResponse {
       // How long does the client have to solve the
       // challenge.
       solve_expiration: Timestamp;
 
       // What is the earlist time at which the client
       // may request a new challenge to be transmitted?
       earliest_retransmission: Timestamp;
     }
 
 Solving challenges
 ^^^^^^^^^^^^^^^^^^
   
 .. http:post:: /accounts/$USERNAME/challenge/$CHALLENGE_ID/confirm
 
   Solves the ``CHALLENGE_ID`` challenge and allows performing the protected operation.
 
   When the challenge is confirmed, you can call the protected endpoint again with ``CHALLENGE_ID`` in the ``Taler-Challenge-Ids`` HTTP header and an the original request body.
 
   This endpoints is not authenticated. Too many unsuccessful attempts to confirm token creation challenges block the account.
 
   **Request:**
 
   .. ts:def:: ChallengeSolve
 
     interface ChallengeSolve {
       // The TAN code that solves $CHALLENGE_ID
       tan: string;
     }
 
   **Response:**
 
   :http:statuscode:`204 No Content`:
     The challenge is confirmed.
   :http:statuscode:`404 Not Found`:
     * ``TALER_EC_BANK_TRANSACTION_NOT_FOUND`` : unknown challenge TAN.
     * ``TALER_EC_BANK_TAN_CHALLENGE_EXPIRED`` : expired challenge.
   :http:statuscode:`409 Conflict`:
     * ``TALER_EC_BANK_TAN_CHALLENGE_FAILED`` : wrong TAN.
     * ``TALER_EC_BANK_TAN_CHALLENGE_EXPIRED`` : expired TAN.
   :http:statuscode:`429 Too many requests`:
     Too many failed confirmation attempts, a new TAN must be requested.
 
 
 Monitor
 -------
 
 .. http:get:: /monitor
 
   When the bank provides conversion between the local currency and an
   external one, this call lets the bank administrator monitor the cashin
   and cashout operations that were made from and to the external currency.
   It shows as well figures related to internal payments made by a Taler
   exchange component to internal bank accounts. Timeframes are in UTC.
 
   **Request:**
 
   :query timeframe: *Optional*.
     This parameter admits one of the following values. Defaults to 'hour'.
 
     * hour
     * day
     * month
     * year
 
   :query date_s: *Optional*.
     Non-negative date in seconds after the UNIX Epoch. Defaults to current time.
     @since **v4**
 
   :query which: *Optional*.
     This parameter points at a particular element of the *timeframe* parameter.
     Following are the admitted values for each one.
     Defaults to the last snapshot taken of the *timeframe* parameter.
     @deprecated since **v4**
 
     * hour: from 00 to 23
     * day: from 1 to the last day of the current month.
     * month: from 1 to 12
     * year: Gregorian year in the YYYY format.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The bank responds with `MonitorResponse`.
   :http:statuscode:`400 Bad Request`:
     This error may indicate that the *which* parameter is not appropriate for the selected *timeframe*.  For example, timeframe=month and which=20 would result in this error.
   :http:statuscode:`401 Unauthorized`:
     Invalid or missing credentials.
   :http:statuscode:`403 Forbidden`:
     Missing rights.
 
   **Details:**
 
   .. note::
 
     API consumers may combine the values in the response with other
     factors to serve different views to their users.
 
   .. ts:def:: MonitorResponse
 
     // Union discriminated by the "type" field.
     type MonitorResponse =
       | MonitorNoConversion
       | MonitorWithConversion;
 
   .. ts:def:: MonitorNoConversion
 
     // Monitoring stats when conversion is not supported
     interface MonitorNoConversion {
       type: "no-conversions";
 
       // How many payments were made to a Taler exchange by another
       // bank account.
       talerInCount: Integer;
 
       // Overall volume that has been paid to a Taler
       // exchange by another bank account.
       talerInVolume: Amount;
 
       // How many payments were made by a Taler exchange to another
       // bank account.
       talerOutCount: Integer;
 
       // Overall volume that has been paid by a Taler
       // exchange to another bank account.
       talerOutVolume: Amount;
     }
 
   .. ts:def:: MonitorWithConversion
 
     // Monitoring stats when conversion is supported
     interface MonitorWithConversion {
       type: "with-conversions";
 
       // How many cashin operations were confirmed by a
       // wallet owner. Note: wallet owners
       // are NOT required to be customers of the libeufin-bank.
       cashinCount: Integer;
 
       // Overall regional currency that has been paid by the regional admin account
       // to regional bank accounts to fulfill all the confirmed cashin operations.
       cashinRegionalVolume: Amount;
 
       // Overall fiat currency that has been paid to the fiat admin account
       // by fiat bank accounts to fulfill all the confirmed cashin operations.
       cashinFiatVolume: Amount;
 
       // How many cashout operations were confirmed.
       cashoutCount: Integer;
 
       // Overall regional currency that has been paid to the regional admin account
       // by fiat bank accounts to fulfill all the confirmed cashout operations.
       cashoutRegionalVolume: Amount;
 
       // Overall fiat currency that has been paid by the fiat admin account
       // to fiat bank accounts to fulfill all the confirmed cashout operations.
       cashoutFiatVolume: Amount;
 
       // How many payments were made to a Taler exchange by another
       // bank account.
       talerInCount: Integer;
 
       // Overall volume that has been paid to a Taler
       // exchange by another bank account.
       talerInVolume: Amount;
 
       // How many payments were made by a Taler exchange to another
       // bank account.
       talerOutCount: Integer;
 
       // Overall volume that has been paid by a Taler
       // exchange to another bank account.
       talerOutVolume: Amount;
     }
 
 
 Endpoints for Integrated Sub-APIs
 ---------------------------------
 
 .. http:any:: /taler-integration/*
 
   All endpoints under this prefix are specified by the.
   :doc:`GNU Taler bank integration API </core/api-bank-integration>`.
   This API handles the communication with Taler wallets.
 
 
 .. http:any:: /accounts/$USERNAME/taler-wire-gateway/*
 
   All endpoints under this prefix are specified
   by the :doc:`GNU Taler wire gateway API </core/api-bank-wire>`.
 
   The endpoints are only available for accounts configured with ``is_taler_exchange=true``.
 
 
 .. http:any:: /accounts/$USERNAME/taler-revenue/*
 
   All endpoints under this prefix are specified
   by the :doc:`GNU Taler Revenue API </core/api-bank-revenue>`.
 
 .. http:any:: /accounts/$USERNAME/conversion-info/*
 
   User custom rates, public for accounts configured with ``is_taler_exchange=true`` else private. Since **v9**
 
   All endpoints under this prefix are specified
   by the :doc:`GNU Taler Conversion Info API </core/api-bank-conversion-info>`.
 
 .. http:any:: /conversion-rate-classes/$CLASS_ID/conversion-info/*
 
   Conversion rate conversion infos, admin only. Since **v9**
 
   All endpoints under this prefix are specified
   by the :doc:`GNU Taler Conversion Info API </core/api-bank-conversion-info>`.
 
 .. http:any:: /conversion-info/*
 
   Global conversion rate infos.
 
   All endpoints under this prefix are specified
   by the :doc:`GNU Taler Conversion Info API </core/api-bank-conversion-info>`.
 
 .. http:any:: /taler-observability/*
 
   Since **v11**
 
   All endpoints under this prefix are specified
   by the :doc:`GNU Taler Observability API </core/api-observability>`.