From b5a2ce02c784d2303e8af203aa5f1a0a930e9c6d Mon Sep 17 00:00:00 2001
From: Christian Grothoff <christian@grothoff.org>
Date: Tue, 5 Oct 2021 15:03:45 +0200
Subject: KYC design update

---
 core/api-exchange.rst | 87 +++++++++++++++------------------------------------
 1 file changed, 26 insertions(+), 61 deletions(-)

(limited to 'core/api-exchange.rst')

diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index dd4450be..4f81f5b7 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -928,54 +928,6 @@ 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.
@@ -3372,35 +3324,48 @@ KYC status updates
      This is a draft API that is not yet implemented.
 
 
-.. http:GET:: /kyc/$PAYMENT_TARGET_UUID
+.. http:POST:: /kyc/$PAYMENT_TARGET_UUID
 
-  Check KYC status of a particular payment target.
-  Prompts the exchange to inquire with the bank
-  as to the KYC status of the respective account
-  and returns the result.
+  Check or update KYC status of a particular payment target.
+  Returns the current KYC status of the account and possibly
+  causes the exchange to inquire with its legitimization
+  resource server as to the KYC status of the respective
+  payment target.
 
   **Request:**
 
   :query timeout_ms=NUMBER: *Optional.*  If specified, the exchange will
-    wait up to ``timeout_ms`` milliseconds for the KYC gateway to
-    confirm completion of the KYC process.
-
+    wait up to ``timeout_ms`` milliseconds if the payment target
+    is currently not legitimized.  Ignored if the payment target
+    is already legitimized. Note that the legitimization would be
+    triggered by another request to the same endpoint with a valid
+    ``token``.
+  :query token=TOKEN: *Optional.* If specified, TOKEN must be an OAuth
+    access token that the exchange can use to verify that the user has
+    an account with the OAuth resource server that holds the
+    legitimization data.
 
   **Response:**
 
   :http:statuscode:`200 Ok`:
     The KYC operation succeeded, the exchange confirms that the
-    payment target will receive payments.
+    payment target is now authorized to transact.
     The response will be an `AccountKycStatus` object.
   :http:statuscode:`202 Accepted`:
     The user should be redirected to the provided location to perform
     the required KYC checks to open the account. Afterwards, the
-    request should be repeated.
+    ``/kyc/`` request should be repeated.
     The response will be an `AccountKycRedirect` object.
+  :http:statuscode:`204 No content`:
+    The exchange is not configured to perform KYC and thus
+    generally all accounts are simply considered legitimate.
+  :http:statuscode:`502 Bad Gateway`:
+    The exchange received an invalid reply from the OAuth-based
+    legitimization service.
   :http:statuscode:`504 Gateway Timeout`:
-    The exchange did not receive a confirmation from the KYC service
-    within the specified time period. Used when long-polling for the
-    result.
+    The exchange did not receive a reply from the OAuth legitimization
+    service within the specified time period. Used when long-polling
+    for the result.
 
   **Details:**
 
-- 
cgit v1.2.3