circuit API: first pass after review

1 files changed, 75 insertions, 57 deletions

diff --git a/libeufin/api-sandbox.rst b/libeufin/api-sandbox.rst
index f4fbb3a2..1bbbec35 100644
--- a/libeufin/api-sandbox.rst
+++ b/libeufin/api-sandbox.rst
@@ -52,43 +52,54 @@ The following endpoints are served under ``/demobanks/default/circuit-api``.
        // Password.
        password: string;
 
-       // E-Mail address
-       email: string;
-
-       // Phone number.
-       phone: string;
+       // Addresses where to send the TAN.  If
+       // this field is missing, then the cashout
+       // won't succeed.
+       contact_data?: CircuitContactData;
 
        // Legal subject owning the account.
        name: string;
 
        // 'payto' address pointing the bank account
        // where to send payments, in case the user
-       // wants to convert the local currency back to
-       // fiat.
-       cashoutAddress: string;
+       // wants to convert the local currency back
+       // to fiat.
+       cashout_address: string;
+
+       // IBAN of this bank account, which is therefore
+       // internal to the circuit.  Randomly generated,
+       // when it is not given.
+       internal_iban?: string;
+     }
+
+   .. ts:def:: CircuitContactData
 
-       // IBAN of this bank account.  Randomly
-       // generated, when it is not given.
-       iban?: string;
+     interface CircuitContactData {
+
+       // E-Mail address
+       email?: string;
+
+       // Phone number.
+       phone?: string;
      }
 
+
    **Response:**
 
    :http:statuscode:`204 No content`:
      The account was successfully created.
-   :http:statuscode:`409 Conflict`: 
-     At least one registration detail was not available,
-     the error message should inform about it.
+   :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 istitutional username was attempted, like ``admin`` or ``bank``. 
+   * A institutional username was attempted, like ``admin`` or ``bank``. 
    * A non admin user tried the operation.
 
-   :http:statuscode:`404 Bad request`:
-     Input data was invalid.  For example, the client specified a invalid
-     phone number or e-mail address.
-
+   :http:statuscode:`409 Conflict`: 
+     At least one registration detail was not available,
+     the error message should inform about it.
 
 .. http:delete:: /accounts/$username
   
@@ -100,17 +111,17 @@ The following endpoints are served under ``/demobanks/default/circuit-api``.
 
   :http:statuscode:`204 No content`:
     The account was successfully deleted.
-  :http:statuscode:`404 Not found`:
-    The username was not found.
   :http:statuscode:`403 Forbidden`:
-    The administrator specified a istitutional username, like
+    The administrator specified a institutional username, like
     ``admin`` or ``bank``.
+  :http:statuscode:`404 Not found`:
+    The username was not found.
   :http:statuscode:`412 Precondition failed`:
     The balance was not zero.
 
 .. _customer-password-modification:
 
-.. http:patch:: /accounts/$username
+.. http:patch:: /accounts/$username/auth
 
    Allows administrators *and* ordinary users to
    change the account's password.
@@ -122,7 +133,7 @@ The following endpoints are served under ``/demobanks/default/circuit-api``.
      interface AccountPasswordChange {
 
        // New password.
-       newPassword: string;
+       new_password: string;
      }
 
    **Response:**
@@ -171,7 +182,7 @@ The following endpoints are served under ``/demobanks/default/circuit-api``.
 
        // 'payto' address pointing the bank account
        // where to send cashouts.
-       cashoutAddress: string;
+       cashout_address: string;
      }
 
 
@@ -219,14 +230,31 @@ The following endpoints are served under ``/demobanks/default/circuit-api``.
 
      interface CashoutRequest {
 
-       // Amount in the $currency:$value format.
-       amount: string; 
+       // 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 amount that the user specified
+       // to cashout.  It is therefore NOT affected by
+       // the exchange rate.
+       amount_before_conversion: string; 
+
+       // That is the amount that will effectively be
+       // transferred by the bank to the user's bank
+       // account external to the circuit.  It therefore
+       // must be affected by the exchange rate.  The
+       // reason to have it here is to force the UI to
+       // calculate this value and show it to the user
+       // before creating the cashout operation.
+       amount_after_conversion: string; 
 
        // 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.
-       tanChannel?: TanChannel;
+       tan_channel?: TanChannel;
      }
 
    **Response:**
@@ -242,10 +270,16 @@ The following endpoints are served under ``/demobanks/default/circuit-api``.
    :http:statuscode:`202 Accepted`:
      The cashout request was correctly created and
      the TAN authentication now is pending.
+   :http:statuscode:`400 Bad request`:
+     The exchange rate was incorrectly applied.
+   :http:statuscode:`403 Forbidden`:
+     A institutional user (``admin`` or ``bank``) tried the operation.
+   :http:statuscode:`409 Forbidden`:
+     The user did not share any contact data where to send the TAN.
    :http:statuscode:`412 Precondition failed`:
      The account does not have sufficient funds.
-   :http:statuscode:`409 Conflict`:
-     A istitutional user (``admin`` or ``bank``) tried the operation.
+   :http:statuscode:`503 Service unavailable`:
+     The bank does not support the TAN channel for this operation.
 
 .. http:post:: /cashouts/$cashoutId/abort
 
@@ -260,24 +294,6 @@ The following endpoints are served under ``/demobanks/default/circuit-api``.
    :http:statuscode:`412 Precondition failed`:
      ``$cashoutId`` was already confirmed or aborted.
 
-.. http:post:: /cashouts/$cashoutId/refresh-tan
-  
-   Invalidates the current TAN of ``$cashoutId`` and
-   send another TAN via the same channel of the previous
-   one.  Only the original author is allowed.
-
-   **Response:**
-
-   :http:statuscode:`204 No content`:
-     ``$cashoutId`` was found in the *pending* state,
-     and a new TAN has been sent via the expected channel.
-   :http:statuscode:`412 Precondition failed`:
-     ``$cashoutId`` was already confirmed or aborted.
-   :http:statuscode:`404 Not found`:
-     ``$cashoutId`` not found.
-   :http:statuscode:`403 Forbidden`:
-     A user other than the original author made the request.
-
 .. http:post:: /cashouts/$cashoutId/confirm
 
    Confirms the ``$cashoutId`` operation by accepting its
@@ -299,15 +315,12 @@ The following endpoints are served under ``/demobanks/default/circuit-api``.
    :http:statuscode:`204 No content`:
      ``$cashoutId`` was found in the *pending* state and
      got successfully  confirmed.
-   :http:statuscode:`412 Precondition failed`:
-     ``$cashoutId`` was already confirmed or aborted.
-   ..
-     412 on a presumably pending operation is a proof
-     of a compromised TAN.
-   :http:statuscode:`401 Unauthorized`:
+   :http:statuscode:`403 Forbidden`:
      wrong TAN.
    :http:statuscode:`409 Conflict`:
-     A istitutional user (``admin`` or ``bank``) tried the operation.
+     A institutional user (``admin`` or ``bank``) tried the operation.
+   :http:statuscode:`412 Precondition failed`:
+     ``$cashoutId`` was already confirmed or aborted.
 
 .. http:get:: /cashouts/$cashoutId
 
@@ -344,6 +357,13 @@ The following endpoints are served under ``/demobanks/default/circuit-api``.
        ABORTED = "aborted"
      }
 
+  **Response:**
+
+  :http:statuscode:`404 Not found`:
+    The cashout operation was not found.  That is
+    *also* the case of ``$cashoutId`` being an aborted
+    operation.
+
 Access API
 ^^^^^^^^^^
 
@@ -779,5 +799,3 @@ The JSON type coming along a non 2xx response is the following:
       */
      UtilError = "util-error"
    }
-
-