[taler-docs] branch master updated: -spec update

[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 58f64cd  -spec update
58f64cd is described below

commit 58f64cdb95e6ecd51c0d9d71d57492861a8fb72e
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Sun Oct 3 14:57:57 2021 +0200

    -spec update
---
 core/api-exchange.rst              | 77 ++++++++++++++++++++++++++++++--
 core/api-merchant.rst              | 91 ++++++++++++++++++++++++++++++++++++++
 design-documents/023-taler-kyc.rst | 20 +++++----
 3 files changed, 176 insertions(+), 12 deletions(-)

diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 5dfbcc3..dd4450b 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -928,9 +928,61 @@ Management operations authorized by master key
     }
 
 
+.. http:post:: /management/kyc
+
+  Clear the KYC setting from some accounts.
+
+  .. note::
+
+     This is a draft API that is not yet implemented.
+
+  **Request:**
+
+  The request must be a `KycRevoke` message.
+
+  **Response**
+
+  :http:statuscode:`200 Ok`:
+    The configuration update has been processed successfully. The body is a 
`KycStatusUpdate` message.
+  :http:statuscode:`403 Forbidden`:
+    The signature is invalid.
+
+  .. ts:def:: KycRevoke
+
+    interface KycRevoke {
+
+      // Signature over a `TALER_KycRevocationPS`.
+      // Basically signes over the hash of the h_wires.
+      master_sig: EddsaSignature;
+
+      // Array of hashes of the payto:// URIs for which to
+      // revoke the KYC check.
+      h_wires: HashCode[];
+
+    }
+
+  .. ts:def:: KycStatusUpdate
+
+    interface KycStatusUpdate {
+
+      // Number of accounts that were disabled.
+      // Note that it is typically expected that many
+      // of the h_wires are simply not in our database
+      // or have previously been disabled. So this only
+      // returns the number of rows that were effectively
+      // changed.
+      num_disabled: Integer;
+
+    }
+
+
 .. http:post:: /management/p2pfees
 
-   Provides fee configuration for purses.
+  Provides fee configuration for purses.
+
+  .. note::
+
+     This is a draft API that is not yet implemented.
 
   **Request:**
 
@@ -948,7 +1000,11 @@ Management operations authorized by master key
 
 .. http:post:: /management/partners
 
-   Enables a partner exchange for wad transfers.
+  Enables a partner exchange for wad transfers.
+
+  .. note::
+
+     This is a draft API that is not yet implemented.
 
   **Request:**
 
@@ -1379,7 +1435,8 @@ exchange.
     transaction or before the client can commit the coin signature to disk, the
     coin is not lost.
   :http:statuscode:`202 Accepted`:
-    This reserve has received funds from a purse and must
+    This reserve has received funds from a purse or the amount withdrawn
+    exceeds another legal threshold and thus the reserve must
     be upgraded to an account (with KYC) before the withdraw can
     complete.  Note that this response does NOT affirm that the
     withdraw will ultimately complete with the requested amount.
@@ -1387,6 +1444,20 @@ exchange.
     the required KYC checks to open the account before withdrawing.
     Afterwards, the request should be repeated.
     The response will be an `AccountKycRedirect` object.
+
+    FIXME: Alternatively, we could return only a
+    PAYMENT_TARGET_UUID and expect the client to
+    then do a ``/kyc/`` request. That might be
+    more uniform with other APIs.
+
+    Implementation note: internally, we need to
+    distinguish between upgrading the reserve to an
+    account (due to P2P payment) and identifying the
+    owner of the origin bank account (due to exceeding
+    the withdraw amount threshold), as we need to create
+    a different payto://-URI for the KYC check depending
+    on the case.
+
   :http:statuscode:`403 Forbidden`:
     The signature is invalid.
   :http:statuscode:`404 Not found`:
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
index bc68ef2..c998154 100644
--- a/core/api-merchant.rst
+++ b/core/api-merchant.rst
@@ -1199,6 +1199,97 @@ Deleting instances
     The latter case only applies if ``purge`` was set.
 
 
+KYC status checks
+-----------------
+
+  .. note::
+
+     This is a draft API that is not yet implemented.
+
+
+.. http:GET:: /management/instances/$INSTANCE/kyc
+.. http:GET:: /instances/$INSTANCE/private/kyc
+
+  Check KYC status of a particular payment target.
+  Prompts the exchange to inquire with the bank
+  as to the KYC status of the respective account
+  and returns the result.
+
+  **Request:**
+
+  :query h_wire=H_WIRE: *Optional*. If specified, the KYC check should return 
the KYC status only for this wire account. Otherwise, for all wire accounts.
+  :query exchange_url=URL: *Optional*. If specified, the KYC check should 
return the KYC status only for the given exchange. Otherwise, for all exchanges 
we interacted with.
+  :query timeout_ms=NUMBER: *Optional.*  If specified, the exchange will
+    wait up to ``timeout_ms`` milliseconds for the exchanges to confirm 
completion of the KYC process(es).
+
+  **Response:**
+
+  If different exchanges cause different errors when processing
+  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.
+    The response will be an `AccountKycRedirects` object.
+  :http:statuscode:`204 No content`:
+    All KYC operations queried have succeeded.
+  :http:statuscode:`502 Bad gateway`:
+    We failed to obtain a response from an exchange (about the KYC status).
+    The response will be an `AccountKycRedirects` object.
+  :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.
+    The response will be an `AccountKycRedirects` object.
+
+  .. ts:def:: AccountKycRedirects
+
+     interface AccountKycRedirects {
+
+       // Array of pending KYCs.
+       pending_kycs: MerchantAccountKycRedirect[];
+
+       // Array of exchanges with no reply.
+       timeout_kycs: ExchangeKycTimeout[];
+    }
+
+  .. ts:def:: MerchantAccountKycRedirect
+
+     interface MerchantAccountKycRedirect {
+
+       // URL that the user should open in a browser to
+       // proceed with the KYC process (as returned
+       // by the exchange's ``/kyc/`` endpoint).
+       kyc_url: string;
+
+       // Base URL of the exchange this is about.
+       exchange_url: string;
+
+       // Our bank wire account this is about.
+       payto_uri: string;
+
+     }
+
+  .. ts:def:: MerchantAccountKycRedirect
+
+     interface MerchantAccountKycRedirect {
+
+       // 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;
+
+    }
+
 --------------------
 Inventory management
 --------------------
diff --git a/design-documents/023-taler-kyc.rst 
b/design-documents/023-taler-kyc.rst
index 12a4cf0..6047997 100644
--- a/design-documents/023-taler-kyc.rst
+++ b/design-documents/023-taler-kyc.rst
@@ -22,20 +22,20 @@ Taler needs to run KYC checks in the following 
circumstances:
 * Customer withdraws money over a monthly threshold
 
   * exchange triggers KYC
-  * key: IBAN
+  * key: IBAN (encoded as payto:// URI)
 
 * Wallet receives (via refunds) money resulting in a balance over a threshold
 
   * this is a client-side restriction
-  * key: reserve (=KYC account) public key (generated, long-term)
+  * key: reserve (=KYC account) long term public key per wallet (encoded as 
payto:// URI)
 
 * Wallet receives money via P2P payments
 
-  * key: reserve (=KYC account) public key
+  * key: reserve (=KYC account) long term public key per wallet (encoded as 
payto:// URI)
 
 * Merchant receives money (Q: any money, or above a monthly threshold?)
 
-  * key: IBAN
+  * key: IBAN (encoded as payto:// URI)
 
 
 
@@ -70,9 +70,11 @@ accounts that were actually modified. The idea is that the 
bank would use this
 to update its KYC records given an updated list of embargoed entities.
 This will also require a new ``taler-exchange-offline`` subcommand.
 
-When withdrawing, the exchange checks if the KYC status is acceptable, and if
-not if the amount withdrawn over the last X days exceeds the threshold.  If
-the check fails, the consumer is redirected to the new ``/kyc/`` handler.
+When withdrawing, the exchange checks if the KYC status is acceptable.  If no
+KYC was done and if either the amount withdrawn over the last X days exceeds
+the threshold or the reserve received received a P2P transfer, then a ``202
+Accepted`` is returned which redirects the consumer to the new ``/kyc/``
+handler.
 
 When depositing, the exchange checks the KYC status and if negative, returns an
 additional information field that tells the merchant the ``wire_target_serial``
@@ -103,8 +105,8 @@ mechant backend receives a ``/kyc/`` response from the 
exchange.  Initially,
 ``kyc_serial`` is zero, indicating that the merchant has not yet made any
 deposits and thus does not have an account at the exchange.
 
-A new private endpoint ``/kyc/`` is introduced which allows frontends to
-request the ``/kyc/`` status of any configured account (including with long
+A new private endpoint ``/kyc`` is introduced which allows frontends to
+request the ``/kyc`` status of any configured account (including with long
 polling).  If the KYC status is negative or the ``kyc_timestamp`` not recent
 (say older than one month), the merchant backend will re-check the KYC status
 at the exchange (and update its cached status).  The endpoint then returns

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