commit 40cbc8c2e78d4203845d5589df6b241861bfbcee
parent 1230914677e2cf3a680179236c3e5c8b1c2b00db
Author: Christian Grothoff <christian@grothoff.org>
Date: Sun, 11 Feb 2024 14:44:18 +0100
clarify documentation for #8056
Diffstat:
1 file changed, 50 insertions(+), 21 deletions(-)
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
@@ -1,6 +1,6 @@
..
This file is part of GNU TALER.
- Copyright (C) 2014-2023 Taler Systems SA
+ Copyright (C) 2014-2024 Taler Systems SA
TALER is free software; you can redistribute it and/or modify it under the
terms of the GNU Affero General Public License as published by the Free Software
@@ -4832,9 +4832,18 @@ wallet-to-wallet payments. Only another exchange should access this endpoint.
KYC status updates
------------------
+This section describes endpoints used to set up, complete and
+inquire about KYC operations performed by an exchange for
+regulatory compliance.
+
.. http:post:: /kyc-wallet
Setup KYC identification for a wallet. Returns the KYC UUID.
+ This endpoint is used by compliant Taler wallets when they
+ are about to hit the balance threshold and thus need to have
+ the customer provide their personal details to the exchange.
+ The wallet is identified by its long-lived reserve public key
+ (which is used for P2P payments, not for withdrawals).
**Request:**
@@ -4891,15 +4900,18 @@ KYC status updates
.. http:get:: /kyc-check/$REQUIREMENT_ROW/$H_PAYTO/$USERTYPE
- 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. The ``$REQUIREMENT_ROW`` 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.
- The ``$USERTYPE`` states whether the entity to perform
- the KYC is an "individual" or "business".
+ Checks the KYC status of a particular payment target and possibly begins the
+ KYC process. This endpoint is used by wallets or merchants that have been
+ told about a KYC requirement and now want to check if the KYC requirement
+ has been fulfilled. Long-polling may be used to instantly observe a change
+ in the KYC requirement status.
+
+ Returns the current KYC status of the requirement process and, if negative,
+ returns the URL where the KYC process can be initiated. The
+ ``$REQUIREMENT_ROW`` 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. The ``$USERTYPE`` states
+ whether the entity to perform the KYC is an "individual" or a "business".
**Request:**
@@ -4918,12 +4930,13 @@ KYC status updates
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
- ``/kyc-check/`` request should be repeated.
+ the required KYC checks to satisfy the legal requirements. Afterwards, the
+ ``/kyc-check/`` request should be repeated to check whether the
+ user has completed the process.
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.
+ the legal requirements are already satisfied.
:http:statuscode:`402 Payment Required`:
The client must pay the KYC fee for the KYC process.
**This is currently not implemented, see #7365.**
@@ -4933,6 +4946,10 @@ KYC status updates
The payment target is unknown.
:http:statuscode:`451 Unavailable for Legal Reasons`:
The transaction cannot be completed due to AML rules.
+ Thus, the operation is currently not stuck on KYC, but
+ on exchange staff performing their AML review. The user
+ should be told to wait and/or contact the exchange operator
+ if the situation persists.
The response will be a `AccountAmlBlocked` object.
**Details:**
@@ -5003,10 +5020,18 @@ KYC status updates
.. http:get:: /kyc-proof/$PROVIDER_SECTION?state=$H_PAYTO
- Update KYC status of a particular payment target. Provides
+ Endpoint accessed from the user's browser at the *end* of a
+ KYC process, possibly providing the exchange with additional
+ credentials to obtain the results of the KYC process.
+ Specifically, the URL arguments should provide
information to the exchange that allows it to verify that the
user has completed the KYC process. The details depend on
- the logic, which is selected by the $PROVIDER_SECTION.
+ the logic, which is selected by the "$PROVIDER_SECTION".
+
+ While this is a GET (and thus safe, and idempotent), the operation
+ may actually trigger significant changes in the exchange's state.
+ In particular, it may update the KYC status of a particular
+ payment target.
**Request:**
@@ -5025,6 +5050,10 @@ KYC status updates
**Response:**
+ Given that the response is returned to a user using a browser and **not** to
+ a Taler wallet, the response format is in human-readable HTML and not in
+ machine-readable JSON.
+
:http:statuscode:`302 Found`:
The KYC operation succeeded and the
payment target is now authorized to transact.
@@ -5047,11 +5076,11 @@ KYC status updates
.. 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 or
- $PROVIDER_SECTION.
+ All of the above endpoints can be used to update KYC status of a particular
+ payment target. They provide 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 the specific "$LOGIC" and/or the
+ "$PROVIDER_SECTION".
**Request:**
@@ -5061,7 +5090,7 @@ KYC status updates
**Response:**
:http:statuscode:`204 No content`:
- The webhook succeeded.
+ The operation succeeded.
:http:statuscode:`404 Not found`:
The specified logic is unknown.
