commit 24902458fe0c0d2293de8dc268b13ab3c6546807
parent 28619609a0b46f0729c31f7fdeef14289e0fb0d6
Author: Florian Dold <florian@dold.me>
Date: Fri, 17 Nov 2023 12:39:03 +0100
split out conversion info API
Diffstat:
3 files changed, 156 insertions(+), 90 deletions(-)
diff --git a/core/api-bank-conversion-info.rst b/core/api-bank-conversion-info.rst
@@ -0,0 +1,147 @@
+..
+ This file is part of GNU TALER.
+
+ Copyright (C) 2014-2023 Taler Systems SA
+
+ TALER is free software; you can redistribute it and/or modify it under the
+ terms of the GNU Affero General Public License as published by the Free Software
+ Foundation; either version 2.1, or (at your option) any later version.
+
+ TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License along with
+ TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+
+ @author Marcello Stanisci
+ @author Christian Grothoff
+ @author Florian Dold
+
+=========================
+Taler Conversion Info API
+=========================
+
+This chapter describes the conversion info API. The conversion info API
+is used by wallets for withdrawals that involve a currency conversion.
+
+
+.. contents:: Table of Contents
+
+.. http:get:: /config
+
+ Get configuration information about the bank.
+
+ **Response:**
+
+ :http:statuscode:`200 OK`:
+ The exchange responds with a `IntegrationConfig` object. This request should
+ virtually always be successful.
+
+ **Details:**
+
+ .. ts:def:: IntegrationConfig
+
+ 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".
+ version: string;
+
+ // Currency used by this bank.
+ currency: string;
+
+ // Name of the API.
+ name: "taler-conversion-info";
+ }
+
+
+.. http:get:: /cashin-rate
+
+ This public endpoint allows clients to calculate
+ the exchange rate between the regional currency
+ and the fiat currency of the banking system.
+
+ This endpoint shows how the bank would apply the cash-in
+ ratio and fee to one input amount. Typically, wallets would
+ request this endpoint before creating withdrawals that involve
+ a currency conversion.
+
+ **Request:**
+
+ :query amount_debit: this is the amount that the user will get
+ deducted from their fiat bank account.
+
+ or
+
+ :query amount_credit: this is the amount that the user will receive
+ in their regional bank account.
+
+ **Response:**
+
+ :http:statuscode:`200 OK`:
+ Response is a `CashinConversionResponse`.
+ :http:statuscode:`400 Bad request`:
+ * ``TALER_EC_GENERIC_PARAMETER_MISSING`` : none of the parameters have been provided.
+ * ``TALER_EC_GENERIC_PARAMETER_MALFORMED`` : both of the parameters have been provided or one of them is not a valid Taler amount.
+ * ``TALER_EC_GENERIC_CURRENCY_MISMATCH`` : the parameter is in the wrong currency.
+ :http:statuscode:`409 Conflict`:
+ The amount is too small to be converted, either because it produces produce an amount less than zero, or because the server requires a higher minimum amount than that supplied.
+ :http:statuscode:`501 Not implemented`:
+ This server does not support conversion or this specific conversion is not currently supported.
+
+ **Details:**
+
+ .. ts:def:: CashinConversionResponse
+
+ interface CashinConversionResponse {
+ // Amount that the user will get deducted from their fiat
+ // bank account, according to the 'amount_credit' value.
+ amount_debit: Amount;
+ // Amount that the user will receive in their regional
+ // bank account, according to 'amount_debit'.
+ amount_credit: Amount;
+ }
+
+.. http:get:: /cashout-rate
+
+ This public endpoint allows clients to calculate
+ the exchange rate between the regional currency
+ and the fiat currency of the banking system.
+
+ 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-in operations.
+
+ **Request:**
+
+ :query amount_debit: this is the amount that the user will get
+ deducted from their regional bank account.
+ :query amount_credit: this is the amount that the user will receive
+ in their fiat bank account.
+
+ **Response:**
+
+ :http:statuscode:`200 OK`:
+ Response is a `CashoutConversionResponse`.
+ :http:statuscode:`400 Bad request`:
+ * ``TALER_EC_GENERIC_PARAMETER_MISSING`` : none of the parameters have been provided.
+ * ``TALER_EC_GENERIC_PARAMETER_MALFORMED`` : both of the parameters have been provided or one of them is not a valid Taler amount.
+ * ``TALER_EC_GENERIC_CURRENCY_MISMATCH`` : the parameter is in the wrong currency.
+ :http:statuscode:`409 Conflict`:
+ The amount is too small to be converted, either because it produces produce an amount less than zero, or because the server requires a higher minimum amount than that supplied.
+ :http:statuscode:`501 Not implemented`:
+ This server does not support conversion or this specific conversion is not currently supported.
+
+ **Details:**
+
+ .. 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;
+ }
diff --git a/core/api-bank-integration.rst b/core/api-bank-integration.rst
@@ -1,7 +1,7 @@
..
This file is part of GNU TALER.
- Copyright (C) 2014-2020 Taler Systems SA
+ Copyright (C) 2014-2023 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
diff --git a/core/api-corebank.rst b/core/api-corebank.rst
@@ -972,95 +972,6 @@ Cashouts
.. _cashout-rates:
-.. http:get:: /cashout-rate
-
- This public endpoint allows clients to calculate
- the exchange rate between the regional currency
- and the fiat currency of the banking system.
-
- 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-in operations.
-
- **Request:**
-
- :query amount_debit: this is the amount that the user will get
- deducted from their regional bank account.
- :query amount_credit: this is the amount that the user will receive
- in their fiat bank account.
-
- **Response:**
-
- :http:statuscode:`200 OK`:
- Response is a `CashoutConversionResponse`.
- :http:statuscode:`400 Bad request`:
- * ``TALER_EC_GENERIC_PARAMETER_MISSING`` : none of the parameters have been provided.
- * ``TALER_EC_GENERIC_PARAMETER_MALFORMED`` : both of the parameters have been provided or one of them is not a valid Taler amount.
- * ``TALER_EC_GENERIC_CURRENCY_MISMATCH`` : the parameter is in the wrong currency.
- :http:statuscode:`409 Conflict`:
- The amount is too small to be converted, either because it produces produce an amount less than zero, or because the server requires a higher minimum amount than that supplied.
- :http:statuscode:`501 Not implemented`:
- This server does not support conversion or this specific conversion is not currently supported.
-
- **Details:**
-
- .. 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:get:: /cashin-rate
-
- This public endpoint allows clients to calculate
- the exchange rate between the regional currency
- and the fiat currency of the banking system.
-
- This endpoint shows how the bank would apply the cash-in
- ratio and fee to one input amount. Typically, wallets would
- request this endpoint before creating withdrawals that involve
- a currency conversion.
-
- **Request:**
-
- :query amount_debit: this is the amount that the user will get
- deducted from their fiat bank account.
-
- or
-
- :query amount_credit: this is the amount that the user will receive
- in their regional bank account.
-
- **Response:**
-
- :http:statuscode:`200 OK`:
- Response is a `CashinConversionResponse`.
- :http:statuscode:`400 Bad request`:
- * ``TALER_EC_GENERIC_PARAMETER_MISSING`` : none of the parameters have been provided.
- * ``TALER_EC_GENERIC_PARAMETER_MALFORMED`` : both of the parameters have been provided or one of them is not a valid Taler amount.
- * ``TALER_EC_GENERIC_CURRENCY_MISMATCH`` : the parameter is in the wrong currency.
- :http:statuscode:`409 Conflict`:
- The amount is too small to be converted, either because it produces produce an amount less than zero, or because the server requires a higher minimum amount than that supplied.
- :http:statuscode:`501 Not implemented`:
- This server does not support conversion or this specific conversion is not currently supported.
-
- **Details:**
-
- .. ts:def:: CashinConversionResponse
-
- interface CashinConversionResponse {
- // Amount that the user will get deducted from their fiat
- // bank account, according to the 'amount_credit' value.
- amount_debit: Amount;
- // Amount that the user will receive in their regional
- // bank account, according to 'amount_debit'.
- amount_credit: Amount;
- }
Monitor
-------
@@ -1212,6 +1123,14 @@ Taler Revenue API
All endpoints under this prefix are specified
by the :doc:`GNU Taler Revenue API </core/api-bank-revenue>`.
+Taler Conversion Info API
+-------------------------
+
+.. http:any:: /conversion-info/*
+
+ All endpoints under this prefix are specified
+ by the :doc:`GNU Taler Revenue API </core/api-bank-conversion-info>`.
+
EBICS Host
----------
