Customer API: new endpoints.

1 files changed, 118 insertions, 35 deletions

diff --git a/libeufin/api-sandbox.rst b/libeufin/api-sandbox.rst
index 8c6d46cb..9a11217f 100644
--- a/libeufin/api-sandbox.rst
+++ b/libeufin/api-sandbox.rst
@@ -23,10 +23,12 @@ APIs are then served.  The following sections describe all such APIs.
 Customer API
 ^^^^^^^^^^^^
 
-This API allows CRUD operations on the bank's customers (also referred
-as 'users').  All the calls are allowed for the administrator, whereas
-**only** the `password change <customer-password-modification_>`_ is allowed
-for ordinary customers.
+This API offers CRUD operations on the bank's customers (or *users*)
+and sending funds between fixed bank accounts.  This last operation
+can be used to *cashout* LibEuFin assets to fiat currency.
+
+For brevity, the list of response statuses for each endpoint may not
+always include all possible cases.
 
 .. note::
    This API requires to **disable** ordinary registrations in the
@@ -37,7 +39,7 @@ The following endpoints are served under ``/demobanks/default/customer-api``.
 
 .. http:post:: /customers
 
-   Create a new customer, including their bank account.
+   Create a new customer, including their bank account.  Only admin allowed.
 
    **Request:**
 
@@ -63,7 +65,7 @@ The following endpoints are served under ``/demobanks/default/customer-api``.
        // where to send payments, in case the customer
        // wants to convert the local currency back to
        // fiat.
-       payoutAddress: string;
+       cashoutAddress: string;
 
        // IBAN to assign to this bank account.  Randomly
        // generated, when it is not given.
@@ -84,13 +86,10 @@ The following endpoints are served under ``/demobanks/default/customer-api``.
      phone number or e-mail.
 
 
-.. http:delete:: /customers
+.. http:delete:: /customers/$username
   
-  Delete a customer *with a zero balance* from the bank.
-
-  **Request:**
-
-  :query username: the username of the customer account to delete.
+  Delete the customer with username ``$username``.  The deletion
+  succeeds only if the customer's balance is *zero*.  Only admin allowed.
 
   **Response:**
 
@@ -109,7 +108,7 @@ The following endpoints are served under ``/demobanks/default/customer-api``.
 .. http:patch:: /customers
 
    Allows administrators *and* ordinary customers to
-   change customer password.
+   change the customer's password.
 
    **Request:**
 
@@ -139,20 +138,25 @@ The following endpoints are served under ``/demobanks/default/customer-api``.
 
 .. http:get:: /customers
 
-   Allows the administrator to obtain a list of all the
-   customers registered at the bank.  It returns only the
-   customer data (without any business information), because
-   :doc:`Access API </core/api-bank-access>` may already
-   be used for that.
+   Obtains a list of all the customers registered at the bank.
+   It returns only the customer data (without any business information),
+   because :doc:`Access API </core/api-bank-access>` may already be used for that.
+   Only admin allowed.
 
    **Response:**
 
+   `Customers <customers-response_>`_
+
+   .. _customers-response:
+
    .. ts:def:: Customers
 
      interfaces Customers {
        customers: CustomerData[]; 
      }
 
+   .. _customer-data:
+
    .. ts:def:: CustomerData
      
      interface CustomerData {
@@ -179,16 +183,32 @@ The following endpoints are served under ``/demobanks/default/customer-api``.
      }
 
 
+.. http:get:: /customers/$username
+
+   Obtains information relative to the customer with username ``$username``.
+   Admin and customer themselves allowed.
+
+   **Response:**
+
+   `CustomerData <customer-data_>`_
+
+   :http:statuscode:`200 OK`:
+     Customer found and credentials correct.
+   :http:statuscode:`403 Forbidden`:
+     Unallowed user tried the operation.
+
 .. http:post:: /cashouts
 
-   Lets the user specify an amount to be converted back
-   to fiat currency.  The target account is the one specified
-   at registration time.  The account to be debited is extracted
-   from the authentication credentials.  The bank sends a TAN
-   to the customer, to let them confirm the operation.
+   Initiates a conversion to fiat currency.  The target account
+   is the one specified at registration time.  The account to be
+   debited is extracted from the authentication credentials.
+   The bank sends a TAN to the customer to let them confirm the
+   operation.  Only customers (= no admin) are allowed.
 
    **Request:**
 
+   `CashoutRequest <cashout-request_>`_
+
    .. ts:def:: TanChannel
 
      enum TanChannel {
@@ -196,6 +216,8 @@ The following endpoints are served under ``/demobanks/default/customer-api``.
        EMAIL = "email"
      }
 
+   .. _cashout-request:
+
    .. ts:def:: CashoutRequest
 
      interface CashoutRequest {
@@ -204,9 +226,9 @@ The following endpoints are served under ``/demobanks/default/customer-api``.
        amount: string; 
 
        // Which channel the TAN should be sent to.  If
-       // this field is missing, it defaults to SMS, to
-       // prefer a different channel than the internet
-       // and let all the phones to receive it.
+       // this field is missing, it defaults to SMS,
+       // since that is a different channel than the
+       // internet.
        tanChannel?: TanChannel;
      }
 
@@ -228,12 +250,39 @@ The following endpoints are served under ``/demobanks/default/customer-api``.
    :http:statuscode:`409 Conflict`:
      A istitutional user (``admin`` or ``bank``) tried the operation.
 
+.. http:post:: /cashouts/$cashoutId/abort
 
-.. http:post:: /cashouts/$cashoutId
+   Aborts the ``$cashoutId`` operation.  Original author
+   *and* admin are allowed.
 
-   Confirms the cashout with UUID $cashoutId by
-   accepting its TAN.  Please note that the request
-   should still be authenticated with the users credentials.
+   **Response:**
+
+   :http:statuscode:`204 No content`:
+     cashout successfully 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
+   TAN.  The request should still be authenticated with
+   the users credentials.  Only the original author is allowed.
 
    **Request:**
 
@@ -241,21 +290,55 @@ The following endpoints are served under ``/demobanks/default/customer-api``.
      
      interface CashoutConfirm {
 
-       // the TAN that was shared by the bank that
-       // confirms $cashoutId.
+       // the TAN that confirms $cashoutId.
        tan: string;
      }
 
-
    **Response:**
    
-   :http:statuscode:`200 OK`:
-     cashout confirmed.
+   :http:statuscode:`204 No content`:
+     cashout confirmed; also returned when using the same TAN
+     more than once.
    :http:statuscode:`401 Unauthorized`:
      wrong TAN.
    :http:statuscode:`409 Conflict`:
      A istitutional user (``admin`` or ``bank``) tried the operation.
 
+.. http:get:: /cashouts/$cashoutId
+
+   Informs about the status of the ``$cashoutId`` operation.
+   Original author and admin are allowed.
+
+   **Response:**
+
+   `CashoutStatusResponse <cashout-status_>`_
+
+   .. _cashout-status:
+
+   .. ts:def:: CashoutStatus
+
+     interface CashoutStatusResponse {
+
+       status: CashoutStatus;
+     }
+
+   .. ts:def:: CashoutStatus
+     
+     enum CashoutStatus {
+
+       // The customer sent a valid TAN and the
+       // bank initiated the payment.
+       CONFIRMED = "confirmed",
+
+       // The cashout was created and now waits
+       // the TAN by the customer.
+       PENDING = "pending",
+
+       // The cashout was aborted before the
+       // confirmation.
+       ABORTED = "aborted"
+     }
+
 Access API
 ^^^^^^^^^^