commit 527b305e9fdf6d4bc47ca8cbaac75923f8e5392e
parent b4ce985452cd0c1a3f2f01c7a3d15bb2b1c3aa19
Author: Antoine A <>
Date: Wed, 1 Nov 2023 11:29:46 +0000
Update bank spec
Diffstat:
2 files changed, 99 insertions(+), 94 deletions(-)
diff --git a/core/api-bank-integration.rst b/core/api-bank-integration.rst
@@ -33,14 +33,14 @@ to tightly integrate with GNU Taler.
**Response:**
:http:statuscode:`200 OK`:
- The exchange responds with a `BankVersion` object. This request should
+ The exchange responds with a `IntegrationConfig` object. This request should
virtually always be successful.
**Details:**
- .. ts:def:: BankVersion
+ .. ts:def:: IntegrationConfig
- interface BankVersion {
+ interface IntegrationConfig {
// 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".
@@ -147,15 +147,13 @@ for the withdrawal operation (the ``wopid``) to interact with the withdrawal ope
The bank does not know about a withdrawal operation with the specified ``wopid``.
:http:statuscode:`409 Conflict`:
* ``TALER_EC_BANK_WITHDRAWAL_OPERATION_RESERVE_SELECTION_CONFLICT`` :
- The wallet selected a different exchange or reserve public key under the same withdrawal ID.
+ The wallet selected a different exchange or reserve public key under the same withdrawal ID.
* ``TALER_EC_BANK_DUPLICATE_RESERVE_PUB_SUBJECT`` : the reserve public key is already used.
* ``TALER_EC_BANK_ACCOUNT_NOT_FOUND`` : the selected exchange account was not found.
* ``TALER_EC_BANK_ACCOUNT_IS_NOT_EXCHANGE`` : the selected account is not an exchange.
**Details:**
-
-
.. ts:def:: BankWithdrawalOperationPostResponse
interface BankWithdrawalOperationPostResponse {
diff --git a/core/api-corebank.rst b/core/api-corebank.rst
@@ -83,6 +83,14 @@ Config
// are not supported and return 404.
have_cashout?: boolean;
+ // If 'true' anyone can register
+ // If 'false' only the admin can
+ allow_registrations: boolean;
+
+ // If 'true' account can delete themselves
+ // If 'false' only the admin can delete accounts
+ allow_deletions: boolean;
+
// How the bank SPA should render the currency.
currency: CurrencySpecification;
@@ -107,7 +115,6 @@ Config
// Fee to subtract after applying the sell ratio.
sell_out_fee: DecimalNumber;
}
-
}
@@ -145,6 +152,7 @@ Account Management
// have a valid reserve public key are automatically
// - the account provides the taler-wire-gateway-api endpoints
// Defaults to false.
+ // Only admin can set this property.
is_taler_exchange?: boolean;
// Addresses where to send the TAN for transactions.
@@ -185,15 +193,15 @@ Account Management
: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:`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
+ * A non-admin user tried to create an exchange account
: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``
.. _delete-account:
@@ -207,15 +215,13 @@ Account Management
: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 account pointed by ``$USERNAME`` was not found.
:http:statuscode:`409 Conflict`:
- The account balance was not zero.
-
+ * ``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:
@@ -243,25 +249,29 @@ Account Management
// back to fiat currency outside the bank.
cashout_address?: string;
- // Legal name associated with $username.
- // When missing, the old name is kept.
+ // If present, change the legal name associated with $username.
+ // Only admin can change this property.
name?: string;
- // If present, change the is_exchange configuration.
+ // If present, change the is_taler_exchange configuration.
// See `RegisterAccountRequest`
- is_exchange?: boolean;
+ // Only admin can change this property.
+ is_taler_exchange?: boolean;
+
+ // If present, change the max debit allowed for this user
+ // Only admin can change this property.
+ debit_threshold?: Amount
}
**Response:**
:http:statuscode:`204 No content`:
Operation successful.
+ :http:statuscode:`401 Unauthorized`:
+ Invalid credentials or missing rights.
: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.
+ * An admin account tried to make its account an exchange
+ * A non-admin user tried to change properties reserved for the admin
:http:statuscode:`404 Not found`:
The account pointed by ``$USERNAME`` was not found.
@@ -270,32 +280,32 @@ Account Management
.. http:patch:: /accounts/$USERNAME/auth
- Allows changing the account's password.
-
+ Allows changing the account's password.
+
- **Request:**
+ **Request:**
- .. ts:def:: AccountPasswordChange
+ .. 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;
- }
+ interface AccountPasswordChange {
+ // Old password. If present it need to match the current
+ // password before updating.
+ old_password?: string;
+ // New password.
+ new_password: string;
+ }
- **Response:**
+ **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.
- :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.
+ :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:`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.
.. _account-list:
@@ -341,59 +351,59 @@ Account Management
.. 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:**
+ **Request:**
- :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.
+ :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:**
+ **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:`403 Forbidden`:
- A ordinary user invoked this call.
+ :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.
- **Details:**
+ **Details:**
- .. ts:def:: ListBankAccountsResponse
+ .. ts:def:: ListBankAccountsResponse
- interfaces ListBankAccountsResponse {
- accounts: AccountMinimalData[];
- }
+ interfaces ListBankAccountsResponse {
+ accounts: AccountMinimalData[];
+ }
- .. ts:def:: Balance
+ .. ts:def:: Balance
- interface Balance {
- amount: Amount;
- credit_debit_indicator: "credit" | "debit";
- }
+ interface Balance {
+ amount: Amount;
+ credit_debit_indicator: "credit" | "debit";
+ }
- .. ts:def:: AccountMinimalData
+ .. ts:def:: AccountMinimalData
- interface AccountMinimalData {
- // Username
- username: string;
+ interface AccountMinimalData {
+ // Username
+ username: string;
- // Legal name of the account owner.
- name: string;
+ // Legal name of the account owner.
+ name: string;
- // current balance of the account
- balance: Balance;
+ // current balance of the account
+ balance: Balance;
- // 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;
+ }
.. _bank-account-info:
@@ -408,10 +418,7 @@ Account Management
: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`:
The account pointed by ``$USERNAME`` was not found.
@@ -483,7 +490,7 @@ Transactions
:http:statuscode:`204 No content`:
No transaction 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.
@@ -503,10 +510,10 @@ Transactions
:http:statuscode:`200 OK`:
The bank responds with an `BankAccountTransactionInfo` object.
+ :http:statuscode:`401 Unauthorized`:
+ Invalid credentials or missing rights.
:http:statuscode:`404 Not found`:
The account pointed by ``$USERNAME`` was not found.
- :http:statuscode:`401 Unauthorized`:
- Invalid credentials.
**Details:**
@@ -1146,7 +1153,7 @@ Taler Wire Gateway API
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
----------------------
