commit 0e69894467fdd3eb68dccde4a9e40d081f54e0a3
parent 4d7e7fa25aeb61faf206349528bfc87fa2753e26
Author: Christian Grothoff <christian@grothoff.org>
Date: Thu, 3 Oct 2024 10:44:42 +0200
bank API version bumps for c2ec: #9233
Diffstat:
2 files changed, 54 insertions(+), 40 deletions(-)
diff --git a/core/api-bank-integration.rst b/core/api-bank-integration.rst
@@ -29,7 +29,7 @@ to tightly integrate with GNU Taler.
.. http:get:: /config
Return the protocol version and configuration information about the bank.
- This specification corresponds to ``current`` protocol being **v3**.
+ This specification corresponds to ``current`` protocol being **v4**.
**Response:**
@@ -52,7 +52,7 @@ to tightly integrate with GNU Taler.
version: string;
// URN of the implementation (needed to interpret 'revision' in version).
- // @since v2, may become mandatory in the future.
+ // @since **v2**, may become mandatory in the future.
implementation?: string;
// Currency used by this bank.
@@ -79,11 +79,11 @@ for the withdrawal operation (the ``WITHDRAWAL_ID``) to interact with the withdr
**Request:**
:query timeout_ms: *Optional.*
- Timeout in milliseconds, for :ref:`long-polling <long-polling>`, to wait for operation state to be different from ``old_state``. Since protocol v3.
+ Timeout in milliseconds, for :ref:`long-polling <long-polling>`, to wait for operation state to be different from ``old_state``. Since protocol **v3**.
:query old_state:
*Optional.* Defaults to "pending".
:query long_poll_ms: *Optional.*
- Deprecated in protocol v3. Use *timeout_ms* instead.
+ Deprecated in protocol **v3**. Use *timeout_ms* instead.
**Response:**
@@ -108,36 +108,36 @@ for the withdrawal operation (the ``WITHDRAWAL_ID``) to interact with the withdr
// Currency used for the withdrawal.
// MUST be present when amount is absent.
- // @since v2, may become mandatory in the future.
+ // @since **v2**, may become mandatory in the future.
currency?: string;
// 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 **vC2EC**.
+ // Optional since **v4**.
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 **vC2EC**.
+ // Optional since **v4**.
suggested_amount?: Amount;
// Minimum amount that the wallet can choose to withdraw.
// Only applicable when the amount is not fixed.
- // @since **vC2EC**.
+ // @since **v4**.
min_amount?: Amount;
// Maximum amount that the wallet can choose to withdraw.
// Only applicable when the amount is not fixed.
- // @since **vC2EC**.
+ // @since **v4**.
max_amount?: Amount;
// The non-Taler card fees the customer will have
// to pay to the bank / payment service provider
// they are using to make the withdrawal in addition
// to the amount.
- // @since **vC2EC**
+ // @since **v4**
card_fees?: Amount;
// Bank account of the customer that is debiting, as an
@@ -152,7 +152,7 @@ for the withdrawal operation (the ``WITHDRAWAL_ID``) to interact with the withdr
// Base URL of an exchange that must be used. Optional,
// not given *unless* a particular exchange is mandatory.
// This value is typically set in the bank's configuration.
- // @since **vC2EC**
+ // @since **v4**
required_exchange?: string;
// URL that the user needs to navigate to in order to
@@ -212,7 +212,7 @@ for the withdrawal operation (the ``WITHDRAWAL_ID``) to interact with the withdr
// Selected amount to be transferred. Optional if the
// backend already knows the amount.
- // @since **vC2EC**
+ // @since **v4**
amount?: Amount;
}
@@ -230,10 +230,10 @@ for the withdrawal operation (the ``WITHDRAWAL_ID``) to interact with the withdr
* ``TALER_EC_BANK_UNKNOWN_ACCOUNT``: the selected exchange account was not found.
* ``TALER_EC_BANK_ACCOUNT_IS_NOT_EXCHANGE``: the selected account is not an exchange.
* ``TALER_EC_BANK_AMOUNT_DIFFERS`` : the specified amount will not work for this
- withdrawal (since **vC2EC**).
+ withdrawal (since **v4**).
* ``TALER_EC_BANK_AMOUNT_REQUIRED`` : the backend requires an amount to be
- specified (since **vC2EC**).
- * ``TALER_EC_BANK_UNALLOWED_DEBIT`` : the account does not have sufficient funds or the amount is too low or too high (since **vC2EC**).
+ specified (since **v4**).
+ * ``TALER_EC_BANK_UNALLOWED_DEBIT`` : the account does not have sufficient funds or the amount is too low or too high (since **v4**).
**Details:**
diff --git a/core/api-corebank.rst b/core/api-corebank.rst
@@ -31,6 +31,7 @@ Introduction
The Libeufin bank provides a minimal core banking system. In addition to that,
it provides features for local/regional currencies.
+
Authentication
--------------
@@ -69,7 +70,7 @@ client to authenticate as the admin.
refreshable?: boolean;
// Optional token description
- // @since v4
+ // @since **v4**
description?: string;
}
@@ -102,7 +103,7 @@ client to authenticate as the admin.
.. http:get:: /accounts/$USERNAME/tokens
Retrieve a subset of tokens related to $USERNAME.
- @since v4
+ @since **v4**
**Request:**
@@ -168,7 +169,7 @@ Config
.. http:get:: /config
Return the protocol version and configuration information about the bank.
- This specification corresponds to ``current`` protocol being version **5**.
+ This specification corresponds to ``current`` protocol being version **v6**.
**Response:**
@@ -190,12 +191,12 @@ Config
// 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.
+ // @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.
+ // @since **v4**.
base_url?: string;
// If 'true' the server provides local currency conversion support
@@ -232,19 +233,19 @@ Config
// Wire transfer type supported by the bank.
// Defaults to 'iban' is missing
- // @since v4, will become mandatory in the next version.
+ // @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.
+ // @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.
+ // @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.
+ // @since **v4**, will become mandatory in the next version.
max_wire_transfer_amount?: Amount;
}
@@ -307,7 +308,7 @@ Account Management
// If present, set a custom minimum cashout amount for this account.
// Only admin can set this property
- // @since v4
+ // @since **v4**
min_cashout?: Amount;
// If present, enables 2FA and set the TAN channel used for challenges
@@ -391,7 +392,7 @@ Account Management
// If present, change the custom minimum cashout amount for this account.
// Only admin can set this property
- // @since v4
+ // @since **v4**
min_cashout?: Amount;
// If present, enables 2FA and set the TAN channel used for challenges
@@ -527,7 +528,7 @@ Account Management
is_taler_exchange: boolean;
// Opaque unique ID used for pagination.
- // @since v4, will become mandatory in the next version.
+ // @since **v4**, will become mandatory in the next version.
row_id?: Integer;
}
@@ -599,7 +600,7 @@ Account Management
// Custom minimum cashout amount for this account.
// If null or absent, the global conversion fee is used.
- // @since v4
+ // @since **v6**
min_cashout?: Amount;
// Is this account visible to anyone?
@@ -609,7 +610,7 @@ Account Management
is_taler_exchange: boolean;
// Opaque unique ID used for pagination.
- // @since v4, will become mandatory in the next version.
+ // @since **v4**, will become mandatory in the next version.
row_id?: Integer;
// Current status of the account
@@ -617,7 +618,7 @@ Account Management
// 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.
+ // @since **v4**, will become mandatory in the next version.
status?: "active" | "deleted";
}
@@ -657,7 +658,7 @@ Account Management
// Custom minimum cashout amount for this account.
// If null or absent, the global conversion fee is used.
- // @since v4
+ // @since **v6**
min_cashout?: Amount;
// Addresses where to send the TAN for transactions.
@@ -689,7 +690,7 @@ Account Management
// 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.
+ // @since **v4**, will become mandatory in the next version.
status?: "active" | "deleted";
}
@@ -788,7 +789,7 @@ Transactions
// 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.
+ // @since **v4**, will become mandatory in the next version.
request_uid?: ShortHashCode;
}
@@ -846,12 +847,12 @@ Account withdrawals
interface BankAccountCreateWithdrawalRequest {
// Amount to withdraw. If given, the wallet
// cannot change the amount.
- // Optional since **vC2EC**.
+ // Optional since **v6**.
amount?: Amount;
// Suggested amount to withdraw. The wallet can
// still change the suggestion.
- // @since **vC2EC**
+ // @since **v6**
suggested_amount?: Amount;
}
@@ -871,6 +872,19 @@ Account withdrawals
withdrawal operation. This call is responsible for wiring the funds to the
exchange.
+ **Request:**
+
+ .. ts:def:: BankWithdrawalOperationPostRequest
+
+ interface BankWithdrawalOperationPostRequest {
+
+ // Selected amount to be transferred. Optional if the
+ // backend already knows the amount.
+ // @since **v6**
+ amount?: Amount;
+ }
+
+
**Response:**
:http:statuscode:`202 Accepted`:
@@ -935,13 +949,13 @@ Account withdrawals
// 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 **vC2EC**.
+ // 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 **vC2EC**.
+ // Optional since **v6**.
suggested_amount?: Amount;
// Account username
@@ -1079,7 +1093,7 @@ Cashouts
**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 protocol v5.
+ At most return the given number of results. Negative for descending by ``cashout_id``, positive for ascending by ``cashout_id``. Defaults to ``-20``. Since protocol **v5**.
:query offset: *Optional.*
Starting ``cashout_id`` for :ref:`pagination <row-id-pagination>`. Since protocol v5.
:query delta: *Optional.*
@@ -1260,13 +1274,13 @@ Monitor
:query date_s: *Optional*.
Non-negative date in seconds after the UNIX Epoch. Defaults to current time.
- @since v4
+ @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
+ @deprecated since **v4**
* hour: from 00 to 23
* day: from 1 to the last day of the current month.
