update KYC DD based on discussions with Martin

1 files changed, 46 insertions, 16 deletions

diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 4f81f5b7..d25c2e52 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -3324,26 +3324,23 @@ KYC status updates
      This is a draft API that is not yet implemented.
 
 
-.. http:POST:: /kyc/$PAYMENT_TARGET_UUID
+.. http:GET:: /kyc-check/$PAYMENT_TARGET_UUID
 
   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.
+  Returns the current KYC status of the account and, if
+  negative, returns the URL where the KYC process can be
+  initiated using OAuth.
 
   **Request:**
 
+  :query h_payto=HASH: Specifies the hash of the payto:// URI of the payment
+    target. Weak security check used to authorize the status request.
   :query timeout_ms=NUMBER: *Optional.*  If specified, the exchange will
     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:**
 
@@ -3359,13 +3356,10 @@ KYC status updates
   :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 reply from the OAuth legitimization
-    service within the specified time period. Used when long-polling
-    for the result.
+  :http:statuscode:`401 Unauthorized`:
+    The provided hash does not match the payment target.
+  :http:statuscode:`404 Not found`:
+    The payment target is unknown.
 
   **Details:**
 
@@ -3396,3 +3390,39 @@ KYC status updates
       kyc_url: string;
 
     }
+
+
+.. http:GET:: /kyc-proof/$PAYMENT_TARGET_UUID
+
+  Update KYC status of a particular payment target. Provides
+  the token to the exchange that allows it to verify that the
+  user has completed the KYC process. The HTTP method must be
+  a GET due to requirements from the OAuth 2.0 protocol.
+
+  **Request:**
+
+  :query code=CODE: OAuth 2.0 code argument.
+  :query state=CODE: OAuth 2.0 state argument.
+
+    ..note::
+
+      Depending on the OAuth variant used, additional
+      query parameters may need to be passed here.
+
+  **Response:**
+
+  :http:statuscode:`302 Found`:
+    The KYC operation succeeded and the
+    payment target is now authorized to transact.
+    The browser is redirected to a human-readable
+    page configured by the exchange operator.
+  :http:statuscode:`401 Unauthorized`:
+    The provided OAuth 2.0 authentication token is invalid.
+  :http:statuscode:`404 Not found`:
+    The payment target is unknown.
+  :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 reply from the OAuth legitimization
+    service within a reasonable time period.