From e5eda6b631a266f90312a11a608ff037b9ec0d56 Mon Sep 17 00:00:00 2001
From: Christian Grothoff <christian@grothoff.org>
Date: Thu, 4 Aug 2022 15:33:16 +0200
Subject: -document new KYC API

---
 core/api-exchange.rst | 63 ++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 45 insertions(+), 18 deletions(-)

diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 0f966f03..59734a98 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -1849,10 +1849,10 @@ exchange.
   .. ts:def:: KycNeededRedirect
 
     interface KycNeededRedirect {
-      // Payment target that the merchant should
+      // Legitimization target that the merchant should
       // use to check for its KYC status using
-      // the ``/kyc-check/$PAYMENT_TARGET_UUID`` endpoint.
-      payment_target_uuid: Integer;
+      // the ``/kyc-check/$LEGITIMIZATION_UUID`` endpoint.
+      legitimization_uuid: Integer;
 
     }
 
@@ -3324,10 +3324,10 @@ typically also view the balance.)
 
     interface TrackTransactionAcceptedResponse {
 
-      // Payment target that the merchant should
+      // Legitimization target that the merchant should
       // use to check for its KYC status using
-      // the ``/kyc-check/$PAYMENT_TARGET_UUID`` endpoint.
-      payment_target_uuid: Integer;
+      // the ``/kyc-check/$LEGITIMIZATION_UUID`` endpoint.
+      legitimization_uuid: Integer;
 
       // True if the KYC check for the merchant has been
       // satisfied.
@@ -4230,17 +4230,18 @@ KYC status updates
      }
 
 
-.. http:GET:: /kyc-check/$PAYMENT_TARGET_UUID
+.. http:GET:: /kyc-check/$LEGITIMIZATION_UUID/$H_PAYTO
 
   Check or update KYC status of a particular 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.
+  initiated.  The LEGITIMIZATION_UUID must have been
+  returned previously from an exchange API endpoint that
+  determined that KYC was needed.  The H_PATYO must be
+  the hash of the payto:// URI of the payment target.
 
   **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
@@ -4252,7 +4253,7 @@ KYC status updates
 
   :http:statuscode:`200 Ok`:
     The KYC operation succeeded, the exchange confirms that the
-    payment target is now authorized to transact.
+    payment target already 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
@@ -4298,15 +4299,20 @@ KYC status updates
     }
 
 
-.. http:GET:: /kyc-proof/$H_PAYTO
+.. http:GET:: /kyc-proof/$H_PAYTO/$LOGIC
 
   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.
+  information to the exchange that allows it to verify that the
+  user has completed the KYC process. The details depend on
+  the logic.
 
   **Request:**
 
+  Details on the request depend on the specific KYC logic
+  that was used.
+
+  If $LOGIC is "oauth2.0", the query parameters are:
+
   :query code=CODE:  OAuth 2.0 code argument.
   :query state=CODE: OAuth 2.0 state argument.
 
@@ -4323,12 +4329,33 @@ KYC status updates
     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.
+    The provided authorization 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
+    The exchange received an invalid reply from the
     legitimization service.
   :http:statuscode:`504 Gateway Timeout`:
-    The exchange did not receive a reply from the OAuth legitimization
+    The exchange did not receive a reply from the legitimization
     service within a reasonable time period.
+
+
+.. http:GET:: /kyc-webhook/$LOGIC/*
+.. http:POST:: /kyc-webhook/$LOGIC/*
+
+  Update KYC status of a particular payment target. Provides
+  information to the KYC logic of the exchange that allows
+  it to verify that the user has completed the KYC process.
+  May be a GET or a POST request, depending on $LOGIC.
+
+  **Request:**
+
+  Details on the request depend on the specific KYC logic
+  that was used.
+
+  **Response:**
+
+  :http:statuscode:`204 No content`:
+    The webhook succeeded.
+  :http:statuscode:`404 Not found`:
+    The specified logic is unknown.
-- 
cgit v1.2.3