Update bank spec

2 files changed, 124 insertions, 132 deletions

diff --git a/core/api-bank-wire.rst b/core/api-bank-wire.rst
index a3474597..3a196d7a 100644
--- a/core/api-bank-wire.rst
+++ b/core/api-bank-wire.rst
@@ -51,7 +51,7 @@ Making Transactions
 
     interface TransferRequest {
       // Nonce to make the request idempotent.  Requests with the same
-      // ``transaction_uid`` that differ in any of the other fields
+      // ``request_uid`` that differ in any of the other fields
       // are rejected.
       request_uid: HashCode;
 
@@ -83,7 +83,7 @@ Making Transactions
   :http:statuscode:`404 Not found`:
     The endpoint is wrong or the user name is unknown. The bank replies with an `ErrorDetail` object.
   :http:statuscode:`409 Conflict`:
-    A transaction with the same ``transaction_uid`` but different transaction details
+    A transaction with the same ``request_uid`` but different transaction details
     has been submitted before.
 
   **Details:**
diff --git a/core/api-corebank.rst b/core/api-corebank.rst
index 57085f23..f3aff449 100644
--- a/core/api-corebank.rst
+++ b/core/api-corebank.rst
@@ -244,7 +244,7 @@ Account Management
       // Payments will be sent to this bank account
       // when the user wants to convert the local currency
       // back to fiat currency outside the bank.
-      cashout_address?: string;
+      cashout_payto_uri?: string;
 
       // If present, change the legal name associated with $username.
       // Only admin can change this property.
@@ -608,8 +608,8 @@ Taler Withdrawals
 
 .. http:post:: ${BANK_API_BASE_URL}/withdrawals/${withdrawal_id}/abort
 
-  Abort a withdrawal operation.  Has no effect on an already aborted
-  withdrawal operation.  Does not require further authentication as knowledge
+  Aborts ``withdrawal_id`` operation.  Has no effect on an already aborted
+  operation.  Does not require further authentication as knowledge
   of the withdrawal ID serves as an authenticator.
 
   **Response:**
@@ -617,13 +617,13 @@ Taler Withdrawals
   :http:statuscode:`204 No content`: 
     The withdrawal operation has been aborted.
   :http:statuscode:`404 Not found`:
-    The operation was not found
+    The withdrawal operation was not found.
   :http:statuscode:`409 Conflict`: 
-    The reserve operation has been confirmed previously and can't be aborted.
+    The withdrawal operation has been confirmed previously and can't be aborted.
 
 .. http:post:: ${BANK_API_BASE_URL}/withdrawals/${withdrawal_id}/confirm
 
-  Confirm a withdrawal operation.  Has no effect on an already confirmed
+  Confirms ``withdrawal_id`` operation.  Has no effect on an already confirmed
   withdrawal operation.  This call is responsible for wiring the funds to the
   exchange.  Does not require further authentication as knowledge of the
   withdrawal ID serves as an authenticator.
@@ -633,7 +633,7 @@ Taler Withdrawals
   :http:statuscode:`204 No content`:
     The withdrawal operation has been confirmed.
   :http:statuscode:`404 Not found`:
-    The operation was not found
+    The operation was not found.
   :http:statuscode:`409 Conflict`:
     * ``TALER_EC_BANK_CONFIRM_ABORT_CONFLICT`` : the withdrawal has been aborted previously and can't be confirmed.
     * ``TALER_EC_BANK_CONFIRM_INCOMPLETE`` : the withdraw operation cannot be confirmed because no exchange and reserve public key selection happened before.
@@ -687,80 +687,70 @@ Cashouts
 
 .. http:post:: /accounts/$USERNAME/cashouts
 
-   Initiates a conversion to fiat currency.  The external
-   bank account to be
-   credited is the one specified at registration time via the
-   *cashout_address* parameter.  The bank internal 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
-   to the administrator.
-
-   .. note::
-
-     Consult the `cashout rates call <cashout-rates_>`_ to learn
-     about any applicable fee or exchange rate.
-
-   .. note::
-
-     FIXME: Eventually, the env variables will be replaced with
-     configuration settings.
-
-     To test this operation without relying on any SMS/E-mail provider,
-     Libeufin offers two methods: defining an environment variable called
-     ``LIBEUFIN_CASHOUT_TEST_TAN`` or specifying the value ``file`` to
-     the ``tan_channel`` field of the `CashoutRequest`.
-     Assuming ``LIBEUFIN_CASHOUT_TEST_TAN`` is set to *T*, every */confirm*
-     operation can use *T* as the TAN.  Setting instead the ``tan_channel``
-     field to ``file`` will cause the server to (over)write every TAN to
-     ``/tmp/cashout-tan.txt``.  If both are used, the environment
-     variable takes the precedence.
-
-
-   **Request:**
-
-   .. ts:def:: TanChannel
-
-     enum TanChannel {
-       SMS = "sms",
-       EMAIL = "email",
-       FILE = "file"
-     }
-
-   .. ts:def:: CashoutRequest
-
-     interface CashoutRequest {
-
-       // 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 plain amount that the user specified
-       // to cashout.  Its $currency is the (regional) currency of the
-       // bank instance.
-       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.
-       // It is expressed in the fiat currency and
-       // is calculated after the cashout fee and the
-       // exchange rate.  See the /cashout-rates call.
-       // The client needs to calculate this amount
-       // correctly based on the amount_debit and the cashout rate,
-       // otherwise the request will fail.
-       amount_credit: Amount;
-
-       // 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.
-       tan_channel?: TanChannel;
-     }
-
-   **Response:**
+  Initiates a conversion to fiat currency.  The external
+  bank account to be
+  credited is the one specified at registration time via the
+  *cashout_payto_uri* parameter.  The bank internal 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
+  to the administrator.
+
+  The same request can be posted several times to trigger TAN retransmission. 
+
+  .. note::
+
+    Consult the `cashout rates call <cashout-rates_>`_ to learn
+    about any applicable fee or exchange rate.
+
+
+  **Request:**
+
+  .. ts:def:: TanChannel
+
+    enum TanChannel {
+      SMS = "sms",
+      EMAIL = "email"
+    }
+
+  .. ts:def:: CashoutRequest
+
+    interface CashoutRequest {
+      // Nonce to make the request idempotent.  Requests with the same
+      // ``request_uid`` that differ in any of the other fields
+      // are rejected.
+      request_uid: ShortHashCode;
+
+      // 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 plain amount that the user specified
+      // to cashout.  Its $currency is the (regional) currency of the
+      // bank instance.
+      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.
+      // It is expressed in the fiat currency and
+      // is calculated after the cashout fee and the
+      // exchange rate.  See the /cashout-rates call.
+      // The client needs to calculate this amount
+      // correctly based on the amount_debit and the cashout rate,
+      // otherwise the request will fail.
+      amount_credit: Amount;
+
+      // 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.
+      tan_channel?: TanChannel;
+    }
+
+  **Response:**
 
   :http:statuscode:`202 Accepted`:
     The cashout request was correctly created and
@@ -769,73 +759,75 @@ Cashouts
   :http:statuscode:`404 Not found`:
     The account pointed by ``$USERNAME`` was not found.
   :http:statuscode:`409 Conflict`:
+    * ``TALER_EC_BANK_TRANSFER_REQUEST_UID_REUSED``: an operation with the same ``request_uid`` but different details has been submitted before.
     * ``TALER_EC_BANK_BAD_CONVERSION`` : exchange rate was calculated incorrectly by the client.
-    * ``TALER_EC_BANK_MISSING_TAN_INFO`` : the user did not share any contact data where to send the TAN with this channel.
+    * ``TALER_EC_BANK_MISSING_TAN_INFO`` : the user did not share any contact data where to send the TAN via ``tan_channel``.
     * ``TALER_EC_BANK_UNALLOWED_DEBIT`` : the account does not have sufficient funds.
+  :http:statuscode:`501 Not Implemented`:
+    The chosen ``tan_channel`` is not currently supported.
+  :http:statuscode:`502 Bad Gateway`:
+    TAN transmition via ``tan_channel`` failed.
 
+  **Details:**
 
-   **Details:**
-
-   .. ts:def:: CashoutPending
+  .. ts:def:: CashoutPending
 
-     interface CashoutPending {
-       // ID identifying the operation being created
-       // and now waiting for the TAN confirmation.
-       cashout_id: string;
-     }
+    interface CashoutPending {
+      // ID identifying the operation being created
+      // and now waiting for the TAN confirmation.
+      cashout_id: string;
+    }
 
 
 .. _cashout-abort:
 
 .. http:post:: /accounts/$USERNAME/cashouts/$CASHOUT_ID/abort
 
-   Aborts the ``$CASHOUT_ID`` operation.
+  Aborts ``CASHOUT_ID`` operation. Has no effect on an already aborted
+  operation.
 
-   **Response:**
-
-   :http:statuscode:`204 No content`:
-     ``$CASHOUT_ID`` was found in the *pending* state
-     and got successfully aborted.
-   :http:statuscode:`404 Not found`:
-     ``$CASHOUT_ID`` is not found.  Note: that happens
-     also when ``$CASHOUT_ID`` got aborted before this request.
-   :http:statuscode:`409 Conflict`:
-     ``$CASHOUT_ID`` was already confirmed.
-   :http:statuscode:`503 Service unavailable`:
-     This server does not support cashout, client should check config response.
+  **Response:**
 
+  :http:statuscode:`204 No content`:
+    The cashout operation has been aborted.
+  :http:statuscode:`404 Not found`:
+    The cashout operation was not found.
+  :http:statuscode:`409 Conflict`:
+    The cashout operation has been confirmed previously and can't be aborted.
 
 .. _cashout-confirm:
 
 .. http:post:: /accounts/$USERNAME/cashouts/$CASHOUT_ID/confirm
 
-   Confirms the ``$CASHOUT_ID`` operation by providing its
-   TAN.  The request should still be authenticated with
-   the users credentials.
-
-   **Request:**
-
-   .. ts:def:: CashoutConfirm
-
-     interface CashoutConfirm {
-       // the TAN that confirms $CASHOUT_ID.
-       tan: string;
-     }
-
-   **Response:**
-
-   :http:statuscode:`204 No content`:
-     The request succeeded, either for the first time, or it already was
-     confirmed previously (idempotency!).
-   :http:statuscode:`403 Forbidden`:
-     Wrong TAN or bad credentials.
-   :http:statuscode:`404 Not found`:
-     ``$CASHOUT_ID`` is not found.  Note: that happens
-     also when ``$CASHOUT_ID`` got aborted before this request.
-   :http:statuscode:`409 Conflict`:
-     The user changed their cash-out address between the creation and the confirmation of ``$CASHOUT_ID``.
-   :http:statuscode:`503 Service unavailable`:
-     This server does not support cashout, client should check config response.
+  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.
+
+  **Request:**
+
+  .. ts:def:: CashoutConfirm
+
+    interface CashoutConfirm {
+      // the TAN that confirms $CASHOUT_ID.
+      tan: string;
+    }
+
+  **Response:**
+
+  :http:statuscode:`204 No content`:
+    The cashout operation has been confirmed.
+  :http:statuscode:`403 Forbidden`:
+    Wrong TAN or expired TAN.
+  :http:statuscode:`404 Not found`:
+    The operation was not found.
+  :http:statuscode:`409 Conflict`:
+    * ``TALER_EC_BANK_CONFIRM_ABORT_CONFLICT`` : the cashout has been aborted previously and can't be confirmed.
+    * ``TALER_EC_BANK_CONFIRM_INCOMPLETE`` : the user did not share any contact data where to send the TAN via ``tan_channel``.
+    * ``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`:
+    Too many failed confirmation attempts, a new TAN must be requested.
 
 .. _circuit-cashouts: