-spec update

1 files changed, 74 insertions, 3 deletions

diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 5dfbcc31..dd4450be 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -928,9 +928,61 @@ Management operations authorized by master key
     }
 
 
+.. http:post:: /management/kyc
+
+  Clear the KYC setting from some accounts.
+
+  .. note::
+
+     This is a draft API that is not yet implemented.
+
+  **Request:**
+
+  The request must be a `KycRevoke` message.
+
+  **Response**
+
+  :http:statuscode:`200 Ok`:
+    The configuration update has been processed successfully. The body is a `KycStatusUpdate` message.
+  :http:statuscode:`403 Forbidden`:
+    The signature is invalid.
+
+  .. ts:def:: KycRevoke
+
+    interface KycRevoke {
+
+      // Signature over a `TALER_KycRevocationPS`.
+      // Basically signes over the hash of the h_wires.
+      master_sig: EddsaSignature;
+
+      // Array of hashes of the payto:// URIs for which to
+      // revoke the KYC check.
+      h_wires: HashCode[];
+
+    }
+
+  .. ts:def:: KycStatusUpdate
+
+    interface KycStatusUpdate {
+
+      // Number of accounts that were disabled.
+      // Note that it is typically expected that many
+      // of the h_wires are simply not in our database
+      // or have previously been disabled. So this only
+      // returns the number of rows that were effectively
+      // changed.
+      num_disabled: Integer;
+
+    }
+
+
 .. http:post:: /management/p2pfees
 
-   Provides fee configuration for purses.
+  Provides fee configuration for purses.
+
+  .. note::
+
+     This is a draft API that is not yet implemented.
 
   **Request:**
 
@@ -948,7 +1000,11 @@ Management operations authorized by master key
 
 .. http:post:: /management/partners
 
-   Enables a partner exchange for wad transfers.
+  Enables a partner exchange for wad transfers.
+
+  .. note::
+
+     This is a draft API that is not yet implemented.
 
   **Request:**
 
@@ -1379,7 +1435,8 @@ exchange.
     transaction or before the client can commit the coin signature to disk, the
     coin is not lost.
   :http:statuscode:`202 Accepted`:
-    This reserve has received funds from a purse and must
+    This reserve has received funds from a purse or the amount withdrawn
+    exceeds another legal threshold and thus the reserve must
     be upgraded to an account (with KYC) before the withdraw can
     complete.  Note that this response does NOT affirm that the
     withdraw will ultimately complete with the requested amount.
@@ -1387,6 +1444,20 @@ exchange.
     the required KYC checks to open the account before withdrawing.
     Afterwards, the request should be repeated.
     The response will be an `AccountKycRedirect` object.
+
+    FIXME: Alternatively, we could return only a
+    PAYMENT_TARGET_UUID and expect the client to
+    then do a ``/kyc/`` request. That might be
+    more uniform with other APIs.
+
+    Implementation note: internally, we need to
+    distinguish between upgrading the reserve to an
+    account (due to P2P payment) and identifying the
+    owner of the origin bank account (due to exceeding
+    the withdraw amount threshold), as we need to create
+    a different payto://-URI for the KYC check depending
+    on the case.
+
   :http:statuscode:`403 Forbidden`:
     The signature is invalid.
   :http:statuscode:`404 Not found`: