diff options
Diffstat (limited to 'core/api-corebank.rst')
| -rw-r--r-- | core/api-corebank.rst | 1411 |
1 files changed, 748 insertions, 663 deletions
diff --git a/core/api-corebank.rst b/core/api-corebank.rst index 15e91537..e1cb4fb6 100644 --- a/core/api-corebank.rst +++ b/core/api-corebank.rst @@ -1,7 +1,7 @@ .. This file is part of GNU TALER. - Copyright (C) 2014-2020 Taler Systems SA + Copyright (C) 2014-2024 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 @@ -23,6 +23,7 @@ Taler Core Bank API ==================== .. contents:: Table of Contents + :local: Introduction ------------ @@ -61,53 +62,70 @@ Config .. http:get:: /config + Return the protocol version and configuration information about the bank. + This specification corresponds to ``current`` protocol being version **4**. + **Response:** + :http:statuscode:`200 OK`: + Response is a `Config`. + + **Details:** + .. ts:def:: Config interface Config { - // Name of this API, always "taler-corebank". - name: string; + // Name of the API. + name: "taler-corebank"; - // API version in the form $n:$n:$n + // 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; - // If 'true', the server provides local currency - // conversion support. - // If missing or false, some parts of the API - // are not supported and return 404. - have_cashout?: boolean; + // 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; - // How the bank SPA should render the currency. - currency: CurrencySpecification; + // 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; - // Fiat currency. That is the currency in which - // cash-out operations ultimately wire money. - // Only applicable if have_cashout=true. - fiat_currency?: CurrencySpecification; + // If 'true' anyone can register + // If 'false' only admin can + allow_registrations: boolean; - // Extra conversion rate information. - // Only present if conversion is supported and the server opts in - // to report the static conversion rate. - conversion_info?: { - // Exchange rate to buy the local currency from the external one - buy_at_ratio: DecimalNumber; + // If 'true' account can delete themselves + // If 'false' only admin can delete accounts + allow_deletions: boolean; - // Exchange rate to sell the local currency for the external one - sell_at_ratio: DecimalNumber; + // If 'true' anyone can edit their name + // If 'false' only admin can + allow_edit_name: boolean; - // Fee to subtract after applying the buy ratio. - buy_in_fee: DecimalNumber; + // If 'true' anyone can edit their cashout account + // If 'false' only admin can + allow_edit_cashout_payto_uri: boolean; - // Fee to subtract after applying the sell ratio. - sell_out_fee: DecimalNumber; - } + // 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. + // Default to 'iban' is missing + // @since v4, will become mandatory in the next version. + wire_type?: string; + } - :http:statuscode:`200 OK`: - Response is a `Config`. Account Management ------------------ @@ -116,81 +134,99 @@ Account Management .. 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 - username: string; - - // Password. - password: string; - - // Legal name of the account owner - name: string; - - // Defaults to false. - is_public?: boolean; - - // Is this 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; + Create a new bank account. Depending on the configuration, + the account creation is self-serve, or only restricted to + the administrators. - // 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. - challenge_contact_data?: ChallengeContactData; + **Request:** - // 'payto' address pointing a bank account - // external to the bank. - // Payments will be sent to this bank account - // when the user wants to convert the local currency - // back to fiat currency outside bank. - cashout_payto_uri?: string; + .. ts:def:: RegisterAccountRequest - // Internal payto URI of this bank account. - // Used mostly for testing. - internal_payto_uri?: string; - } + interface RegisterAccountRequest { + // Username of the account + username: string; - .. ts:def:: ChallengeContactData + // Password of the account used for authentication + password: string; - interface ChallengeContactData { + // Legal name of the account owner + name: string; - // E-Mail address - email?: EmailAddress; + // 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; + + // IBAN 'payto' URI of a fiat bank account with a 'receiver-name' parameter. + // If 'receiver-name' is missing, ``name`` will be used instead. + // 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; + + // Internal 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, 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; + } - // Phone number. - phone?: PhoneNumber; - } + .. ts:def:: ChallengeContactData + interface ChallengeContactData { + // E-Mail address + email?: EmailAddress; - **Response:** + // Phone number. + phone?: PhoneNumber; + } - :http:statuscode:`201 Created`: - 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 reserved username was attempted, like ``admin`` or ``bank``. - * An unauthorized user tried to create the account + **Response:** - :http:statuscode:`409 Conflict`: - The internal account payto URI or username already exists. + :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 credentials or 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_TAN_CHANNEL`` : a non-admin user has tried to create an account with 2fa. + * ``TALER_EC_BANK_TAN_CHANNEL_NOT_SUPPORTED``: ``tan_channel`` 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``. + + **Details:** + + .. ts:def:: RegisterAccountResponse + + interface RegisterAccountResponse { + // Internal payto URI of this bank account. + internal_payto_uri: string; + } .. _delete-account: @@ -202,119 +238,134 @@ Account Management **Response:** + :http:statuscode:`202 Accepted`: + 2FA is required for this operation. This returns the `Challenge` response. :http:statuscode:`204 No content`: The account was successfully deleted. - :http:statuscode:`403 Forbidden`: - Either the request specified a reserved internal username, like - ``admin`` or ``bank``, or the client didn't have the rights to this - call. + :http:statuscode:`401 Unauthorized`: + Invalid credentials or missing rights. :http:statuscode:`404 Not found`: - The username was not found. - :http:statuscode:`412 Precondition failed`: - The balance was not zero. - + 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-reconfig: .. http:patch:: /accounts/$USERNAME - Allows reconfiguring the account data of ``$USERNAME``. + Allows reconfiguring the account data of ``$USERNAME``. - **Request:** - - .. ts:def:: AccountReconfiguration + **Request:** - interface AccountReconfiguration { + .. ts:def:: AccountReconfiguration - // 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. - challenge_contact_data?: ChallengeContactData; + interface AccountReconfiguration { + // Addresses where to send the TAN for protected operations. + contact_data?: ChallengeContactData; - // 'payto' address pointing a bank account - // external to the bank. - // Payments will be sent to this bank account - // when the user wants to convert the local currency - // back to fiat currency outside the bank. - cashout_address?: string; + // IBAN 'payto' URI of a fiat bank account with a 'receiver-name' parameter. + // If 'receiver-name' is missing, ``name`` will be used instead. + // 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 + cashout_payto_uri?: string; - // Legal name associated with $username. - // When missing, the old name is kept. - name?: string; + // If present, change the legal name associated with $username. + // Only admin can change this property if not allowed in config + name?: string; - // If present, change the is_exchange configuration. - // See `RegisterAccountRequest` - is_exchange?: boolean; - } + // Make this account visible to anyone? + is_public?: boolean; - **Response:** + // If present, change the max debit allowed for this user + // Only admin can change this property. + debit_threshold?: Amount; - :http:statuscode:`204 No content`: - Operation successful. + // If present, enables 2FA and set the TAN channel used for challenges + tan_channel?: TanChannel; + } - :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. + **Response:** - :http:statuscode:`404 Not found`: - The account pointed by ``$USERNAME`` - was not found. + :http:statuscode:`202 Accepted`: + 2FA is required for this operation. This returns the `Challenge` response. + :http:statuscode:`204 No content`: + Operation successful. + :http:statuscode:`401 Unauthorized`: + Invalid credentials or 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_TAN_CHANNEL_NOT_SUPPORTED`` : ``tan_channel`` 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``. .. _account-password-reconfig: .. http:patch:: /accounts/$USERNAME/auth - Allows changing the account's password. - + Allows changing the account's password. - **Request:** - .. ts:def:: AccountPasswordChange + **Request:** - interface AccountPasswordChange { - // Old password. If present it need to match the current - // password before updating. - old_password?: string; - // New password. - new_password: string; - } + .. ts:def:: AccountPasswordChange - **Response:** + interface AccountPasswordChange { + // Old password. If present it need to match the current + // password before updating. + old_password?: string; + // New password. + new_password: string; + } - :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 credentials. - :http:statuscode:`403 Forbidden`: - The user is not allowed to change the ``$USERNAME`` password or - the "old_password" field in the request doesn't match the current pasword. + **Response:** + + :http:statuscode:`202 Accepted`: + 2FA is required for this operation. This returns the `Challenge` response. + :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 credentials or 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. .. _account-list: -.. http:get:: ${BANK_API_BASE_URL}/public-accounts +.. 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 start: *Optional.* - Row identifier to explicitly set the *starting point* of the query. - :query delta: *Optional.* - The *delta* value that determines the range of the query. + **Request:** - **Response** + :query delta: *Optional.* + Takes value of the form ``N (-N)``, so that at most ``N`` values strictly older (younger) than ``start`` are returned. Defaults to ``-20`` to return the last 20 entries. + :query start: *Optional.* + Row number threshold, see ``delta`` for its interpretation. Defaults to smallest or biggest row id possible according to ``delta`` sign. + :query filter_name: *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:** - **Details** + :http:statuscode:`200 OK`: + Response is a `PublicAccountsResponse`. + :http:statuscode:`204 No content`: + No public account. + + **Details:** .. ts:def:: PublicAccountsResponse @@ -325,245 +376,292 @@ Account Management .. ts:def:: PublicAccount interface PublicAccount { + // Username of the account + username: string; + + // Internal payto URI of this bank account. payto_uri: string; + // Current balance of the account balance: Balance; - // The account name (=username) of the - // bank account. - account_name: string; - } + // Is this a taler exchange account? + is_taler_exchange: boolean; - :http:statuscode:`200 OK`: - Response is a `PublicAccountsResponse`. - :http:statuscode:`204 No content`: - No public account. + // 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. + 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 delta: *Optional.* + Takes value of the form ``N (-N)``, so that at most ``N`` values strictly older (younger) than ``start`` are returned. Defaults to ``-20`` to return the last 20 entries. + :query start: *Optional.* + Row number threshold, see ``delta`` for its interpretation. Defaults to smallest or biggest row id possible according to ``delta`` sign. + :query filter_name: *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:** + + :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 credentials or missing rights. - **Request:** + **Details:** - :query filter_name: *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. + .. ts:def:: ListBankAccountsResponse - **Response:** + interfaces ListBankAccountsResponse { + accounts: AccountMinimalData[]; + } - :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:`403 Forbidden`: - A ordinary user invoked this call. + .. ts:def:: Balance - **Details:** + interface Balance { + amount: Amount; + credit_debit_indicator: "credit" | "debit"; + } - .. ts:def:: ListBankAccountsResponse + .. ts:def:: AccountMinimalData - interfaces ListBankAccountsResponse { - accounts: AccountMinimalData[]; - } + interface AccountMinimalData { + // Username of the account + username: string; - .. ts:def:: Balance + // Legal name of the account owner. + name: string; - interface Balance { - amount: Amount; - credit_debit_indicator: "credit" | "debit"; - } + // Internal payto URI of this bank account. + payto_uri: string; - .. ts:def:: AccountMinimalData + // Current balance of the account + balance: Balance; - interface AccountMinimalData { - // Username - username: string; + // Number indicating the max debit allowed for the requesting user. + debit_threshold: Amount; - // Legal name of the account owner. - name: string; + // Is this account visible to anyone? + is_public: boolean; - // current balance of the account - balance: Balance; + // Is this a taler exchange account? + is_taler_exchange: boolean; - // Number indicating the max debit allowed for the requesting user. - debit_threshold: Amount; - } + // Opaque unique ID used for pagination. + // @since v4, will become mandatory in the next version. + row_id?: Integer; + } .. _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. + Obtains information relative to the account owned by + ``$USERNAME``. The request is available to the administrator + and ``$USERNAME`` itself. - **Response:** + **Response:** :http:statuscode:`200 OK`: The bank responds with an `AccountData` object. :http:statuscode:`401 Unauthorized`: - Invalid credentials. - :http:statuscode:`403 Forbidden`: - Credentials are valid but this user has no permission to the - the account info. + Invalid credentials or missing rights. :http:statuscode:`404 Not found`: - Username not found + The account pointed by ``$USERNAME`` was not found. - **Details:** + **Details:** - .. ts:def:: AccountData + .. ts:def:: AccountData - interface AccountData { - // Legal name of the account owner. - name: string; + interface AccountData { + // Legal name of the account owner. + name: string; - // Available balance on the account. - balance: Balance; + // Available balance on the account. + balance: Balance; - // payto://-URI of the account. - payto_uri: string; + // payto://-URI of the account. + payto_uri: string; - // Number indicating the max debit allowed for the requesting user. - debit_threshold: Amount; + // Number indicating the max debit allowed for the requesting user. + debit_threshold: Amount; - contact_data?: ChallengeContactData; + // 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; - // '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_payto_uri?: string; - } + // IBAN 'payto' URI with a 'receiver-name' parameter of a fiat 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_payto_uri?: string; -Transactions ------------- + // Is this account visible to anyone? + is_public: boolean; -.. http:get:: ${BANK_API_BASE_URL}/accounts/${account_name}/transactions + // Is this a taler exchange account? + is_taler_exchange: boolean; - Retrieve a subset of transactions related to $account_name. Without - query parameters, it returns the last 5 transactions. + // Is 2FA enabled and what channel is used for challenges? + tan_channel?: TanChannel; + } - The list of returned transactions is determined by a row ID *starting point* - and a signed non-zero integer *delta*: +Transactions +------------ - * If *delta* is positive, return a list of up to *delta* transactions (all matching - the filter criteria) strictly **after** the starting point. The transactions are sorted - in **ascending** order of the row ID. - * If *delta* is negative, return a list of up to *-delta* transactions (all matching - the filter criteria) strictly **before** the starting point. The transactions are sorted - in **descending** order of the row ID. +.. http:get:: /accounts/$USERNAME/transactions - If *starting point* is not explicitly given, it defaults to: + Retrieve a subset of transactions related to $USERNAME. - * A value that is **smaller** than all other row IDs if *delta* is **positive**. - * A value that is **larger** than all other row IDs if *delta* is **negative**. + The list of returned transactions is determined by a row ID *starting point* + and a signed non-zero integer *delta*: - **Request** + * If *delta* is positive, return a list of up to *delta* transactions (all matching + the filter criteria) strictly **after** the starting point. The transactions are sorted + in **ascending** order of the row ID. + * If *delta* is negative, return a list of up to *-delta* transactions (all matching + the filter criteria) strictly **before** the starting point. The transactions are sorted + in **descending** order of the row ID. - :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 start: *Optional.* - Row identifier to explicitly set the *starting point* of the query. - :query delta: *Optional.* - The *delta* value that determines the range of the query. + If *starting point* is not explicitly given, it defaults to: - **Response** + * A value that is **smaller** than all other row IDs if *delta* is **positive**. + * A value that is **larger** than all other row IDs if *delta* is **negative**. - .. ts:def:: BankAccountTransactionsResponse + **Request:** + + :query delta: *Optional.* + Takes value of the form ``N (-N)``, so that at most ``N`` values strictly older (younger) than ``start`` are returned. Defaults to ``-20`` to return the last 20 entries. + :query start: *Optional.* + Row number threshold, see ``delta`` for its interpretation. Defaults to smallest or biggest row id possible according to ``delta`` sign. + :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. - interface BankAccountTransactionsResponse { - transactions: BankAccountTransactionInfo[]; - } + **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 credentails + Invalid credentials or missing rights. :http:statuscode:`404 Not found`: - Username not found - -.. http:get:: ${BANK_API_BASE_URL}/accounts/${account_name}/transactions/${transaction_id} - - **Response** + The account pointed by ``$USERNAME`` was not found. - Retrieve the transaction whose identifier is ``transaction_id``, - in the following format: + **Details:** - .. ts:def:: BankAccountTransactionInfo + .. ts:def:: BankAccountTransactionsResponse - interface BankAccountTransactionInfo { - creditor_payto_uri: string; - debtor_payto_uri: string; + interface BankAccountTransactionsResponse { + transactions: BankAccountTransactionInfo[]; + } - amount: Amount; - direction: "debit" | "credit"; +.. http:get:: /accounts/$USERNAME/transactions/$TRANSACTION_ID - subject: string; + Retrieve the transaction whose identifier is ``TRANSACTION_ID``. - // Transaction unique ID. Matches - // $transaction_id from the URI. - row_id: number; - date: Timestamp; - } + **Response:** :http:statuscode:`200 OK`: The bank responds with an `BankAccountTransactionInfo` object. - :http:statuscode:`404 Not found`: - Username not found :http:statuscode:`401 Unauthorized`: - Invalid credentials. + Invalid credentials or missing rights. + :http:statuscode:`404 Not found`: + The account pointed by ``$USERNAME`` was not found. + **Details:** -.. http:post:: ${BANK_API_BASE_URL}/accounts/${account_name}/transactions + .. ts:def:: BankAccountTransactionInfo - Create a new transaction where the bank account with the label ``account_name`` is **debited**. + interface BankAccountTransactionInfo { + creditor_payto_uri: string; + debtor_payto_uri: string; - **Request** + amount: Amount; + direction: "debit" | "credit"; - .. ts:def:: BankAccountTransactionCreate + subject: string; - interface CreateBankAccountTransactionCreate { + // Transaction unique ID. Matches + // $TRANSACTION_ID from the URI. + row_id: Integer; + date: Timestamp; + } - // Address in the Payto format of the wire transfer receiver. - // It needs at least the 'message' query string parameter. - payto_uri: string; +.. http:post:: /accounts/$USERNAME/transactions - // 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; - } + Create a new transaction where the bank account with the label ``USERNAME`` is **debited**. - **Response** + **Request:** - :http:statuscode:`204 No content`: - the transaction has been created. + .. 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; + } + + **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 `Challenge` response. :http:statuscode:`400 Bad Request`: - the request was invalid or the payto://-URI used unacceptable features. + The request was invalid or the payto://-URI used unacceptable features. :http:statuscode:`401 Unauthorized`: Invalid credentials. + :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. + + **Details:** + .. ts:def:: CreateTransactionResponse + + interface CreateTransactionResponse { + // ID identifying the transaction being created + row_id: Integer; + } Taler Withdrawals ----------------- -.. http:post:: ${BANK_API_BASE_URL}/accounts/${account_name}/withdrawals +.. http:post:: /accounts/$USERNAME/withdrawals Create a withdrawal operation, resulting in a ``taler://withdraw`` URI. - **Request** + **Request:** .. ts:def:: BankAccountCreateWithdrawalRequest @@ -572,91 +670,110 @@ Taler Withdrawals amount: Amount; } - **Response** + **Response:** + + :http:statuscode:`200 Ok`: + The bank responds with an `BankAccountCreateWithdrawalResponse` object. + :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:: BankAccountCreateWithdrawalResponse interface BankAccountCreateWithdrawalResponse { - // ID of the withdrawal, can be used to view/modify the withdrawal operation. - // This ID will be globally unique and grant control over the operation to - // abort or confirm it. + // ID identifying the operation being created withdrawal_id: string; - // URI that can be passed to the wallet to initiate the withdrawal. + // URI that can be passed to the wallet to initiate the withdrawal taler_withdraw_uri: string; - } + } - :http:statuscode:`200 Ok`: - The bank responds with an `BankAccountCreateWithdrawalResponse` object. - :http:statuscode:`403 Forbidden`: - The operation was rejected due to insufficient funds. +.. http:post:: /accounts/$USERNAME/withdrawals/$WITHDRAWAL_ID/confirm -.. http:get:: ${BANK_API_BASE_URL}/withdrawals/${withdrawal_id} + Confirms ``WITHDRAWAL_ID`` operation. Has no effect on an already confirmed + withdrawal operation. This call is responsible for wiring the funds to the + exchange. - Query the status of a withdrawal operation. Does not require further - authentication as knowledge of the withdrawal ID serves as an authenticator. + **Response:** - **Response** + :http:statuscode:`202 Accepted`: + 2FA is required for this operation. This returns the `Challenge` response. + :http:statuscode:`204 No content`: + The withdrawal operation has been confirmed. + :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. - **Details** +.. http:post:: /accounts/$USERNAME/withdrawals/$WITHDRAWAL_ID/abort - .. ts:def:: BankAccountGetWithdrawalResponse + Aborts ``WITHDRAWAL_ID`` operation. Has no effect on an already aborted + operation. - interface BankAccountGetWithdrawalResponse { - // Amount that will be withdrawn with this withdrawal operation. - amount: Amount; + **Response:** - // Was the withdrawal aborted? - aborted: boolean; + :http:statuscode:`204 No content`: + The withdrawal operation has been aborted. + :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. - // 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; +.. http:get:: /withdrawals/$WITHDRAWAL_ID - // Did the wallet select reserve details? - selection_done: boolean; + Retrieve public information about ``WITHDRAWAL_ID`` withdrawal operation. + Does not require further authentication as knowledge of ``WITHDRAWAL_ID`` + serves as an authenticator. - // Reserve public key selected by the exchange, - // only non-null if ``selection_done`` is ``true``. - selected_reserve_pub: string | null; + **Request:** - // 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; - } + :query long_poll_ms: + *Optional.* If specified, the bank will wait up to ``long_poll_ms`` + milliseconds for operationt state to be different from ``old_state`` before sending the HTTP + response. A client must never rely on this behavior, as the bank may + return a response immediately. + :query old_state: + *Optional.* Default to "pending". + + **Response:** :http:statuscode:`200 Ok`: - The bank responds with an `BankAccountGetWithdrawalResponse` object. + The bank responds with an `WithdrawalPublicInfo` object. :http:statuscode:`404 Not found`: The operation was not found. -.. http:post:: ${BANK_API_BASE_URL}/withdrawals/${withdrawal_id}/abort + **Details:** - Abort a withdrawal operation. Has no effect on an already aborted - withdrawal operation. Does not require further authentication as knowledge - of the withdrawal ID serves as an authenticator. + .. ts:def:: WithdrawalPublicInfo - :http:statuscode:`204 No content`: 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. + 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). + amount: Amount; -.. http:post:: ${BANK_API_BASE_URL}/withdrawals/${withdrawal_id}/confirm - - Confirm a withdrawal operation. Has no effect on an already confirmed - withdrawal operation. This call is responsible for wiring the funds to the - exchange. Does not require further authentication as knowledge of the - withdrawal ID serves as an authenticator. + // Account username + username: string; - **Response** + // Reserve public key selected by the exchange, + // only non-null if ``status`` is ``selected`` or ``confirmed``. + selected_reserve_pub?: string; - :http:statuscode:`204 No content`: - 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. + // Exchange account selected by the wallet + // only non-null if ``status`` is ``selected`` or ``confirmed``. + selected_exchange_account?: string; + } Cashouts -------- @@ -665,223 +782,135 @@ Cashouts .. http:post:: /accounts/$USERNAME/cashouts - Initiates a conversion to fiat currency. The external - bank account to be - credited is the one specified at registration time via the - *cashout_address* parameter. The bank internal account - is specified via ``$USERNAME``. - 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. - - .. note:: - - FIXME: Eventually, the env variables will be replaced with - configuration settings. - - 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/cashout-tan.txt``. If both are used, the environment - variable takes the precedence. - - - **Request:** - - :query start: *Optional.* - Row identifier to explicitly set the *starting point* of the query. - :query delta: *Optional.* - The *delta* value that determines the range of the query. - - `CashoutRequest <cashout-request_>`_ - - .. ts:def:: TanChannel - - enum TanChannel { - SMS = "sms", - EMAIL = "email", - FILE = "file" - } + 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``. - .. _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 (regional) currency of the - // bank instance. - amount_debit: Amount; + .. note:: - // That is the amount that will effectively be - // transferred by the bank to the user's bank - // account, that is external to the regional currency. - // It is expressed in the fiat currency and - // is calculated after the cashout fee and the - // exchange rate. See the /cashout-rates 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; + Consult the `cashout rates call <cashout-rates_>`_ to learn + about any applicable fee or exchange rate. - // 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:** + **Request:** - :http:statuscode:`202 Accepted`: - The cashout request was correctly created and - the TAN authentication now is pending. - This returns the `CashoutPending` response. - :http:statuscode:`409 Conflict`: - The user did not share any contact data where to send the TAN, - the account does not have sufficient funds, or the - exchange rate was calculated incorrectly by the client. - :http:statuscode:`503 Service unavailable`: - The bank does not support the TAN channel for this operation. - The bank does not support cashout, client should check config response. + .. 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; - **Details:** + // 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; - .. ts:def:: CashoutPending + // That is the plain amount that the user specified + // to cashout. Its $currency is the (regional) currency of the + // bank instance. + amount_debit: Amount; - interface CashoutPending { - // ID identifying the operation being created - // and now waiting for the TAN confirmation. - cashout_id: string; - } + // 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:** -.. _cashout-abort: + :http:statuscode:`200 OK`: + The cashout request was correctly created. + This returns the `CashoutPending` response. + :http:statuscode:`202 Accepted`: + 2FA is required for this operation. This returns the `Challenge` response. + :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_UNALLOWED_DEBIT`` : the account does not have sufficient funds. + * ``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`` is not currently supported. + * This server does not support conversion, client should check config response. -.. http:post:: /accounts/$USERNAME/cashouts/$CASHOUT_ID/abort + **Details:** - Aborts the ``$CASHOUT_ID`` operation. + .. ts:def:: CashoutResponse - **Response:** + interface CashoutResponse { + // ID identifying the operation being created + cashout_id: Integer; + } - :http:statuscode:`204 No content`: - ``$CASHOUT_ID`` was found in the *pending* state - and got successfully aborted. - :http:statuscode:`404 Not found`: - ``$CASHOUT_ID`` is not found. Note: that happens - also when ``$CASHOUT_ID`` got aborted before this request. - :http:statuscode:`409 Conflict`: - ``$CASHOUT_ID`` was already confirmed. - :http:statuscode:`503 Service unavailable`: - This server does not support cashout, client should check config response. +.. _circuit-cashout-details: +.. http:get:: /accounts/$USERNAME/cashouts/$CASHOUT_ID -.. _cashout-confirm: + Returns information about the status of the ``$CASHOUT_ID`` operation. + The request is available to the administrator and the account owner. -.. http:post:: /accounts/$USERNAME/cashouts/$CASHOUT_ID/confirm + **Response:** - Confirms the ``$CASHOUT_ID`` operation by providing its - TAN. The request should still be authenticated with - the users credentials. + :http:statuscode:`200 OK`: + Response is a `CashoutStatusResponse`. + :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. - **Request:** + **Details:** - .. ts:def:: CashoutConfirm + .. ts:def:: CashoutStatusResponse - interface CashoutConfirm { - // the TAN that confirms $CASHOUT_ID. - tan: string; - } + interface CashoutStatusResponse { + // Amount debited to the regional bank account. + amount_debit: Amount; - **Response:** + // Amount credited to the fiat bank account. + amount_credit: Amount; - :http:statuscode:`204 No content`: - The request succeeded, either for the first time, or it already was - confirmed previously (idempotency!). - :http:statuscode:`403 Forbidden`: - Wrong TAN or bad credentials. - :http:statuscode:`404 Not found`: - ``$CASHOUT_ID`` is not found. Note: that happens - also when ``$CASHOUT_ID`` got aborted before this request. - :http:statuscode:`409 Conflict`: - The user changed their cash-out address between the creation and the confirmation of ``$CASHOUT_ID``. - :http:statuscode:`503 Service unavailable`: - This server does not support cashout, client should check config response. + // Transaction subject. + subject: string; -.. _cashout-rates: + // Time when the cashout was created. + creation_time: Timestamp; + } -.. http:get:: /cashout-rate +.. _circuit-cashouts: - This public endpoint allows clients to calculate - the exchange rate between the regional currency - and the external banking system. +.. http:get:: /accounts/$USERNAME/cashouts - 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. - At least one of the two query parameters must be provided. If both are - given, then the server checks their correctness. Amounts must include the - currency. + Returns the list of all cash-out operations for an account. **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. + :query delta: *Optional.* + Takes value of the form ``N (-N)``, so that at most ``N`` values strictly older (younger) than ``start`` are returned. Defaults to ``-20`` to return the last 20 entries. + :query start: *Optional.* + Row number threshold, see ``delta`` for its interpretation. Defaults to smallest or biggest row id possible according to ``delta`` sign. **Response:** - .. ts:def:: CashoutConversionResponse - - interface CashoutConversionResponse { - // 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 is a `CashoutConversionResponse`. - :http:statuscode:`400 Bad request`: - Both parameters have been provided and the calculation is not correct, - or none of them has been provided, or the requested currency was not - supported. The response should clarify which case. - :http:statuscode:`404 Not found`: - The server does not support local currency conversion. - :http:statuscode:`503 Service unavailable`: - This server does not support cashout, client should check config response. - - -.. _circuit-cashouts: - -.. http:get:: /accounts/$USERNAME/cashouts + Response is a `Cashouts`. + :http:statuscode:`204 No Content`: + No cash-out operations were found. + :http:statuscode:`501 Not implemented`: + This server does not support conversion, client should check config response. - Returns the list of all the (pending and confirmed) cash-out operations - for an account. - - **Response:** + **Details:** .. ts:def:: Cashouts @@ -893,25 +922,21 @@ Cashouts .. ts:def:: CashoutInfo interface CashoutInfo { - cashout_id: string; - status: "pending" | "confirmed"; + cashout_id: Integer; } - :http:statuscode:`200 OK`: - Response is a `Cashouts`. - :http:statuscode:`204 No Content`: - No cash-out operations were found at the bank - :http:statuscode:`404 Not found`: - Username not fuond. - :http:statuscode:`503 Service unavailable`: - This server does not support cashout, client should check config response. - .. http:get:: /cashouts - Returns the list of all the (pending and confirmed) cash-out operations - for **all** accounts. + Returns the list of all cash-out operations for **all** accounts. + + Can only be used by the administrators. + + **Request:** - Typically can only be used by the administrators. + :query delta: *Optional.* + Takes value of the form ``N (-N)``, so that at most ``N`` values strictly older (younger) than ``start`` are returned. Defaults to ``-20`` to return the last 20 entries. + :query start: *Optional.* + Row number threshold, see ``delta`` for its interpretation. Defaults to smallest or biggest row id possible according to ``delta`` sign. .. note:: @@ -920,77 +945,106 @@ Cashouts **Response:** + :http:statuscode:`200 OK`: + Response is a `GlobalCashouts`. + :http:statuscode:`204 No Content`: + No cash-out operations were found. + :http:statuscode:`501 Not implemented`: + This server does not support conversion, client should check config response. + + **Details:** + .. ts:def:: GlobalCashouts interface GlobalCashouts { - // Every string represents a cash-out operation ID. - cashouts: { cashout_id: string, username: string}[]; + cashouts: GlobalCashoutInfo[]; } .. ts:def:: GlobalCashoutInfo interface GlobalCashoutInfo { - cashout_id: string; + cashout_id: Integer; username: string; - status: "pending" | "confirmed"; } - :http:statuscode:`200 OK`: - Response is a `GlobalCashouts`. - :http:statuscode:`204 No Content`: - No cash-out operations were found at the bank - :http:statuscode:`503 Service unavailable`: - This server does not support cashout, client should check config response. +.. _cashout-rates: -.. _circuit-cashout-details: +2FA +--- -.. http:get:: /accounts/$USERNAME/cashouts/$CASHOUT_ID +.. http:post:: /accounts/$USERNAME/challenge/$CHALLENGE_ID - Returns information about the status of the ``$CASHOUT_ID`` operation. - The request is available to the administrator and the account owner. + 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. **Response:** - `CashoutStatusResponse <cashout-status_>`_ + :http:statuscode:`200 OK`: + The TAN code have been sent. This returns `TanTransmission` response. + :http:statuscode:`401 Unauthorized`: + Invalid credentials or missing rights. + :http:statuscode:`404 Not Found`: + The challenge was not found. + :http:statuscode:`502 Bad Gateway`: + * ``TALER_EC_BANK_TAN_CHANNEL_SCRIPT_FAILED``: TAN transmition via ``tan_channel`` failed. - .. _cashout-status: + **Details:** - .. ts:def:: CashoutStatus + .. ts:def:: TanTransmission - interface CashoutStatusResponse { - status: "pending" | "confirmed"; + interface TanTransmission { + // Channel of the last successful transmission of the TAN challenge. + tan_channel: TanChannel; - // Amount debited to the internal - // regional currency bank account. - amount_debit: Amount; + // Info of the last successful transmission of the TAN challenge. + tan_info: string; + } - // Amount credited to the external bank account. - amount_credit: Amount; + .. ts:def:: Challenge - // Transaction subject. - subject: string; + interface Challenge { + // Unique identifier of the challenge to solve to run this protected + // operation. + challenge_id: string; + } - // Fiat bank account that will receive the cashed out amount. - // Specified as a payto URI. - credit_payto_uri: string; + .. ts:def:: TanChannel - // Time when the cashout was created. - creation_time: Timestamp; + enum TanChannel { + SMS = "sms", + EMAIL = "email" + } + + +.. 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 ``X-Challenge-Id`` HTTP header and an empty request body. + + **Request:** + + .. ts:def:: ChallengeSolve - // Time when the cashout was confirmed via its TAN. - // Missing when the operation wasn't confirmed yet. - confirmation_time?: Timestamp; + interface ChallengeSolve { + // The TAN code that solves $CHALLENGE_ID + tan: string; } **Response:** - :http:statuscode:`200 OK`: - Response is a `CashoutStatusResponse`. - :http:statuscode:`404 Not found`: - The cashout operation was not found. - Aborted cashout operations will also not be found. - :http:statuscode:`503 Service unavailable`: - This server does not support cashout, client should check config response. + :http:statuscode:`204 No Content`: + The challenge is confirmed. + :http:statuscode:`401 Unauthorized`: + Invalid credentials or missing rights. + :http:statuscode:`404 Not Found`: + The challenge was not found. + :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 @@ -1001,8 +1055,8 @@ 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 merchant bank accounts. Timeframes are in UTC. + It shows as well figures related to internal payments made by a Taler + exchange component to internal bank accounts. Timeframes are in UTC. **Request:** @@ -1013,7 +1067,6 @@ Monitor * day * month * year - * decade :query which: *Optional*. This parameter points at a particular element of the *timeframe* parameter. @@ -1024,18 +1077,15 @@ Monitor * day: from 1 to the last day of the current month. * month: from 1 to 12 * year: Gregorian year in the YYYY format. - * decade: the least Y0 digits of a Gregorian year. Banks should treat such decades as starting from the year 2000. For example, if Y=2, this decade denotes the years 2020 to 2029. **Response:** - :http:statuscode:`200 OK`: + :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:`503 Service unavailable`: - The bank doesn't have the conversion service. + **Details:** .. note:: @@ -1044,49 +1094,84 @@ Monitor .. ts:def:: MonitorResponse - interface 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; - // This number identifies how many cashin operations - // took place in the timeframe specified in the request. - // This number corresponds to how many withdrawals have - // been initiated by a wallet owner. Note: wallet owners + // 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. - // Only present if conversion is supported - cashinCount?: number; - - // This amount accounts how much external currency has been - // spent to withdraw Taler coins in the internal currency. - // The exact amount of internal currency being created can be - // calculated using the advertised conversion rates. - // Only present if conversion is supported - cashinExternalVolume?: Amount; - - // This number identifies how many cashout operations were - // confirmed in the timeframe speficied in the request. - // Only present if conversion is supported - cashoutCount?: number; - - // This amount corresponds to how much *external* currency was - // paid by the libeufin-bank administrator to fulfill all the - // confirmed cashouts related to the timeframe specified in the - // request. - // Only present if conversion is supported - cashoutExternalVolume?: Amount; - - // This number identifies how many payments were made by a - // Taler exchange to a merchant bank account in the internal - // currency, in the timeframe specified in the request. - talerPayoutCount: number; - - // This amount accounts the overall *internal* currency that - // has been paid by a Taler exchange to a merchant internal - // bank account, in the timeframe specified in the request. - talerPayoutInternalVolume: Amount; + 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; } -Taler Bank Integration API --------------------------- +Endpoints for Integrated Sub-APIs +--------------------------------- .. http:any:: /taler-integration/* @@ -1094,33 +1179,33 @@ Taler Bank Integration API :doc:`GNU Taler bank integration API </core/api-bank-integration>`. This API handles the communication with Taler wallets. -Taler Wire Gateway API ----------------------- .. 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_exchange=true``. + The endpoints are only available for accounts configured with ``is_taler_exchange=true``. -Taler Revenue API ----------------------- .. http:any:: /accounts/$USERNAME/taler-revenue/* All endpoints under this prefix are specified by the :doc:`GNU Taler Revenue API </core/api-bank-revenue>`. -EBICS Host ----------- -The Taler bank can be configured to serve bank account transactions and allow -payment initiations via the EBICS protocol. +.. http:any:: /conversion-info/* + + All endpoints under this prefix are specified + by the :doc:`GNU Taler Conversion Info API </core/api-bank-conversion-info>`. -This is an optional feature, not all implementations of the API support it. .. http:post:: /ebicshost EBICS base URL. This URL allows clients to make EBICS requests to one of the configured EBICS hosts. + + The Taler bank can be configured to serve bank account transactions and + allow payment initiations via the EBICS protocol. + + This is an optional feature, not all implementations of the API support it. |