[taler-docs] branch master updated: breaking API change: /kyc-check/REQUIREMENT_ROW replaced by H_PAYTO

[gnunet]

This is an automated email from the git hooks/post-receive script.

grothoff pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new cc092f4d breaking API change: /kyc-check/REQUIREMENT_ROW replaced by 
H_PAYTO
cc092f4d is described below

commit cc092f4de2f92cf71347534b2e75fb0fd1b8992a
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Tue Sep 3 01:00:19 2024 +0200

    breaking API change: /kyc-check/REQUIREMENT_ROW replaced by H_PAYTO
---
 core/api-common.rst   | 14 +++++++-------
 core/api-exchange.rst | 31 +++++++++++++++++--------------
 2 files changed, 24 insertions(+), 21 deletions(-)

diff --git a/core/api-common.rst b/core/api-common.rst
index 9df656f6..9c9dee03 100644
--- a/core/api-common.rst
+++ b/core/api-common.rst
@@ -851,6 +851,8 @@ body.
 
     // Hash of the payto:// account URI for which KYC
     // is required.
+    // The account holder can uses the ``/kyc-check/$H_PAYTO``
+    // endpoint to check the KYC status or initiate the KYC process.
     h_payto: PaytoHash;
 
     // Public key associated with the account. The client must sign
@@ -865,13 +867,11 @@ body.
     account_pub?: EddsaPublicKey;
 
     // Identifies a set of measures that were triggered and that are
-    // now preventing this operation from proceeding.  Gives the
-    // account holder a starting point for understanding why the
-    // transaction was blocked and how to lift it. The account holder
-    // should use the number to check for the account's AML/KYC status
-    // using the ``/kyc-check/$REQUIREMENT_ROW`` endpoint.
-    // Can be zero (which means there is no requirement row)
-    // if ``bad_kyc_auth`` is set.
+    // now preventing this operation from proceeding.  Gives developers
+    // a starting point for understanding why the transaction was
+    // blocked and how to lift it.
+    // Can be zero (which means there is no requirement row),
+    // especially if ``bad_kyc_auth`` is set.
     requirement_row: Integer;
 
     // True if the operation was denied because the
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index e7a817bd..7da33a90 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -3777,12 +3777,10 @@ typically also view the balance.)
 
     interface TrackTransactionAcceptedResponse {
 
-      // Legitimization target that the merchant should
-      // use to check for its KYC status using
-      // the ``/kyc-check/$REQUIREMENT_ROW/...`` endpoint.
-      // Optional, not present if the deposit has not
+      // Legitimization row. Largely useless, except
+      // not present if the deposit has not
       // yet been aggregated to the point that a KYC
-      // need has been evaluated.
+      // requirement has been evaluated.
       requirement_row?: Integer;
 
       // Current AML state for the target account. Non-zero
@@ -4745,7 +4743,7 @@ regulatory compliance.
      }
 
 
-.. http:get:: /kyc-check/$REQUIREMENT_ROW
+.. http:get:: /kyc-check/$H_PAYTO
 
   Checks the KYC status of a particular payment target and possibly begins a
   KYC process by allowing the customer to choose the next KYC measure to
@@ -4756,11 +4754,7 @@ regulatory compliance.
   statisfied and the operation can now proceed).  Long-polling may be used
   to instantly observe a change in the KYC requirement status.
 
-  The requirement row of the ``/kyc-check/`` endpoint encodes the
-  legitimization measure's serial number.  It is returned in
-  `LegitimizationNeededResponse` responses via the ``requirement_row`` field.
-
-  Given a valid pair of requirement row and account owner signature, the
+  Given a valid pair of payto hash and account owner signature, the
   ``/kyc-check/`` endpoint returns either just the KYC status or redirects the
   client (202) to the next required stage of the KYC process.  The redirection
   must be for an HTTP(S) endpoint to be triggered via a simple HTTP GET.  It
@@ -4769,7 +4763,7 @@ regulatory compliance.
   that received a 202 status code may repeat the request and use long-polling
   to detect a change of the HTTP status.
 
-  This endpoint exists in this specific form only since protocol **v20**.
+  This endpoint exists in this specific form only since protocol **v21**.
 
   **Request:**
 
@@ -4810,14 +4804,23 @@ regulatory compliance.
     The exchange is not configured to perform KYC and thus
     the legal requirements are already satisfied.
   :http:statuscode:`403 Forbidden`:
-    The provided signature is not acceptable for the requirement row.  The 
(base32) encoding of the public key we expect signatures to be made with is 
returned in the ``detail`` field.
+    The provided signature is not acceptable for the given account.  The 
response will be an `KycCheckAccountExpectedResponse` object which specifies 
the expected account public key.
   :http:statuscode:`404 Not found`:
-    The requirement row is unknown.
+    The account identified by the payto hash is unknown.
   :http:statuscode:`409 Conflict`:
     The bank account is not (yet) associated with a public key. The account 
owner must do a wire transfer to the exchange with the account public key in 
the wire transfer subject to enable authentication.
 
   **Details:**
 
+  .. ts:def:: KycCheckAccountExpectedResponse
+
+    interface KycCheckAccountExpectedResponse {
+
+      // Public key for which the signature must be
+      // valid to authorize this request.
+      expected_account_pub: EddsaPublicKey;
+    }
+
   .. ts:def:: AccountKycStatus
 
     interface AccountKycStatus {

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.