[taler-docs] branch master updated: clean up GET /kyc endpoint, return more comprehensive and consistent data

[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 fc463328 clean up GET /kyc endpoint, return more comprehensive and 
consistent data
fc463328 is described below

commit fc463328c5e9b48c1ea387144ea6d2682faba86c
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Sun Sep 8 18:39:32 2024 +0200

    clean up GET /kyc endpoint, return more comprehensive and consistent data
---
 core/api-merchant.rst | 106 ++++++++++++++++++++++----------------------------
 1 file changed, 46 insertions(+), 60 deletions(-)

diff --git a/core/api-merchant.rst b/core/api-merchant.rst
index 7a7e2e23..0f3443eb 100644
--- a/core/api-merchant.rst
+++ b/core/api-merchant.rst
@@ -1456,29 +1456,16 @@ KYC status checks
   the request, the largest HTTP status code that is applicable
   is returned.
 
-  :http:statuscode:`202 Accepted`:
-    The user should be redirected to the provided locations to perform
-    the required KYC checks to open an account. Afterwards, the
-    request should be repeated.
+  :http:statuscode:`200 Ok`:
+    The user may be redirected to the provided locations to perform
+    KYC checks.
     The response will be a `MerchantAccountKycRedirectsResponse` object.
+    Uses this status code and format only since protocol **v17**.
   :http:statuscode:`204 No content`:
-    All KYC operations queried have succeeded.  This may change in the
-    future, but there is no need to check again soon. It is suggested
-    to check again at a frequency of hours or days.
-  :http:statuscode:`502 Bad gateway`:
-    We failed to obtain a response from an exchange (about the KYC status).
-    The response will be a `MerchantAccountKycRedirectsResponse` object.
-  :http:statuscode:`503 Service unavailable`:
-    We do not know our KYC status as the exchange has not yet
-    returned the necessary details. This is not an actual failure:
-    this is expected to happen if for example a deposit was not yet aggregated
-    by the exchange and thus the exchange has not yet initiated
-    the KYC process. The client should simply try again later. It is
-    suggested to check again at a frequency of minutes to hours.
-  :http:statuscode:`504 Gateway Timeout`:
-    The merchant did not receive a confirmation from an exchange
-    within the specified time period. Used when long-polling for the
-    result.
+    No possibilities for KYC operations exist.
+    This may change in the future, but there is
+    no need to check again soon. This will most likely
+    change if accounts are added to the instance.
 
   **Details:**
 
@@ -1486,25 +1473,59 @@ KYC status checks
 
      interface MerchantAccountKycRedirectsResponse {
 
-       // Array of pending KYCs.
-       pending_kycs: MerchantAccountKycRedirect[];
+       // Array of KYC status information for
+       // the exchanges and bank accounts selected
+       // by the query.
+       kyc_data: MerchantAccountKycRedirect[];
 
-       // Array of exchanges with no reply.
-       timeout_kycs: ExchangeKycTimeout[];
     }
 
   .. ts:def:: MerchantAccountKycRedirect
 
     interface MerchantAccountKycRedirect {
 
+      // Our bank wire account this is about.
+      payto_uri: string;
+
+      // Base URL of the exchange this is about.
+      exchange_url: string;
+
+      // HTTP status code returned by the exchange when we asked for
+      // information about the KYC status.
+      // Since protocol **v17**.
+      exchange_http_status: number;
+
+      // Set to true if we did not get a ``/keys`` response from
+      // the exchange and thus cannot do certain checks, such as
+      // determining default account limits or account eligibility.
+      no_keys: boolean;
+
+      // Set to true if the given account cannot to KYC at the
+      // given exchange because no wire method exists that could
+      // be used to do the KYC auth wire transfer.
+      auth_conflict: boolean;
+
+      // Numeric `error code <error-codes>` indicating errors the exchange
+      // returned, or TALER_EC_INVALID for none.
+      // Optional (as there may not always have
+      // been an error code). Since protocol **v17**.
+      exchange_code?: number;
+
       // URL that the user should open in a browser to
       // proceed with the KYC process (as returned
       // by the exchange's ``/kyc-check/`` endpoint).
       // Optional, missing if the account is blocked
       // due to the need for a KYC auth transfer.
       // (See ``payto_kycauth`` in that case.)
+      // Deprecated since protocol **v17**. Combine
+      // ``exchange_url``, "/kyc-spa/" and ``access_token``
+      // if this is needed instead.
       kyc_url?: string;
 
+      // Access token needed to open the KYC SPA and/or
+      // access the ``/kyc-info/`` endpoint.
+      access_token?: AccountAccessToken;
+
       // Array with limitations that currently apply to this
       // account and that may be increased or lifted if the
       // KYC check is passed.
@@ -1524,23 +1545,6 @@ KYC status checks
       // request that would cause it to exceed hard limits).
       limits?: AccountLimit[];
 
-      // Base URL of the exchange this is about.
-      exchange_url: string;
-
-      // Numeric `error code <error-codes>` indicating errors the exchange
-      // returned, or TALER_EC_INVALID for none.
-      // Optional (as there may not always have
-      // been an error code). Since protocol **v17**.
-      exchange_code?: number;
-
-      // HTTP status code returned by the exchange when we asked for
-      // information about the KYC status.
-      // Since protocol **v17**.
-      exchange_http_status: number;
-
-      // Our bank wire account this is about.
-      payto_uri: string;
-
       // Array of wire transfer instructions (including
       // optional amount and subject) for a KYC auth wire
       // transfer. Set only if this is required
@@ -1553,24 +1557,6 @@ KYC status checks
 
     }
 
-  .. ts:def:: ExchangeKycTimeout
-
-    interface ExchangeKycTimeout {
-
-      // Base URL of the exchange this is about.
-      exchange_url: string;
-
-      // Numeric `error code <error-codes>` indicating errors the exchange
-      // returned, or TALER_EC_INVALID for none.
-      exchange_code: number;
-
-      // HTTP status code returned by the exchange when we asked for
-      // information about the KYC status.
-      // 0 if there was no response at all.
-      exchange_http_status: number;
-
-    }
-
 
 -------------
 Bank Accounts

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