Update bank spec

1 files changed, 92 insertions, 52 deletions

diff --git a/core/api-corebank.rst b/core/api-corebank.rst
index 06e1a895..8ba90d2d 100644
--- a/core/api-corebank.rst
+++ b/core/api-corebank.rst
@@ -161,10 +161,9 @@ Account Management
       // as well.
       challenge_contact_data?: ChallengeContactData;
 
-      // 'payto' address pointing a bank account
-      // external to the bank.
+      // 'payto' address of a fiat bank account.
       // Payments will be sent to this bank account
-      // when the user wants to convert the local currency
+      // when the user wants to convert the regional currency
       // back to fiat currency outside bank.
       cashout_payto_uri?: string;
 
@@ -239,11 +238,10 @@ Account Management
       // as well.
       challenge_contact_data?: ChallengeContactData;
 
-      // 'payto' address pointing a bank account
-      // external to the bank.
+      // 'payto' address of a fiat bank account.
       // Payments will be sent to this bank account
-      // when the user wants to convert the local currency
-      // back to fiat currency outside the bank.
+      // when the user wants to convert the regional currency
+      // back to fiat currency outside bank.
       cashout_payto_uri?: string;
 
       // If present, change the legal name associated with $username.
@@ -687,10 +685,10 @@ Cashouts
 
 .. http:post:: /accounts/$USERNAME/cashouts
 
-  Initiates a conversion to fiat currency.  The external
+  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 bank internal account
+  *cashout_payto_uri* parameter.  The regional bank 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
@@ -724,7 +722,7 @@ Cashouts
       // 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.
+      // the user's fiat bank account.
       subject?: string;
 
       // That is the plain amount that the user specified
@@ -733,11 +731,11 @@ Cashouts
       amount_debit: Amount;
 
       // 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.
+      // 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-rates call.
+      // 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.
@@ -802,7 +800,7 @@ Cashouts
   Confirms ``CASHOUT_ID`` operation by providing its
   TAN. Has no effect on an already confirmed
   cashout operation. This call is responsible for wiring the funds to the
-  user's external bank account.
+  user's fiat bank account.
 
   **Request:**
 
@@ -826,7 +824,7 @@ Cashouts
     * ``TALER_EC_BANK_CONFIRM_INCOMPLETE`` : the user did not share any cashout payto to uri where to wire funds.
     * ``TALER_EC_BANK_UNALLOWED_DEBIT`` : the account does not have sufficient funds.
     * ``TALER_EC_BANK_BAD_CONVERSION`` : exchange rate has changed since operation creation.
-  :http:statuscode:`429 Too Many Request`:
+  :http:statuscode:`429 Too many requests`:
     Too many failed confirmation attempts, a new TAN must be requested.
 
 
@@ -853,11 +851,10 @@ Cashouts
     interface CashoutStatusResponse {
       status: "pending" | "aborted" | "confirmed";
 
-      // Amount debited to the internal
-      // regional currency bank account.
+      // Amount debited to the regional bank account.
       amount_debit: Amount;
 
-      // Amount credited to the external bank account.
+      // Amount credited to the fiat bank account.
       amount_credit: Amount;
 
       // Transaction subject.
@@ -960,14 +957,11 @@ Cashouts
 
   This public endpoint allows clients to calculate
   the exchange rate between the regional currency
-  and the external banking system.
+  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-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.
+  ask this endpoint before creating cash-in operations.
 
   **Request:**
 
@@ -981,13 +975,13 @@ Cashouts
   :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.
+    * ``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 this conversion.
 
   **Details:**
 
@@ -1002,6 +996,52 @@ Cashouts
       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, 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 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 this conversion.
+
+  **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
 -------
 
@@ -1010,8 +1050,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:**
 
@@ -1065,18 +1105,18 @@ Monitor
       type: "no-conversions";
 
       // How many payments were made to a Taler exchange by another
-      // internal bank account.
+      // bank account.
       talerInCount: number;
 
-      // Overall *internal* currency that has been paid to a Taler 
+      // 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
-      // internal bank account.
+      // bank account.
       talerOutCount: number;
 
-      // Overall *internal* currency that has been paid by a Taler 
+      // Overall volume that has been paid by a Taler 
       // exchange to another bank account.
       talerOutVolume: Amount;
     }
@@ -1092,38 +1132,38 @@ Monitor
       // are NOT required to be customers of the libeufin-bank.
       cashinCount: number;
 
-      // Overall *internal* currency that has been paid by the internal admin account
-      // to internal bank accounts to fulfill all the confirmed cashin operations.
-      cashinInternalVolume: Amount;
+      // 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 *external* currency that has been paid to the external admin account
-      // by external bank accounts to fulfill all the confirmed cashin operations.
-      cashinExternalVolume: 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: number;
 
-      // Overall *internal* currency that has been paid to the internal admin account
-      // by internal bank accounts to fulfill all the confirmed cashout operations.
-      cashoutInternalVolume: Amount;
+      // 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 *external* currency that has been paid by the external admin account
-      // to external bank accounts to fulfill all the confirmed cashout operations.
-      cashoutExternalVolume: 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
-      // internal bank account.
+      // bank account.
       talerInCount: number;
 
-      // Overall *internal* currency that has been paid to a Taler 
+      // 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
-      // internal bank account.
+      // bank account.
       talerOutCount: number;
 
-      // Overall *internal* currency that has been paid by a Taler 
+      // Overall volume that has been paid by a Taler 
       // exchange to another bank account.
       talerOutVolume: Amount;
     }