first ideas for KYC API extension

1 files changed, 120 insertions, 90 deletions

diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 3d8d8b7e..5dfbcc31 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -1,6 +1,6 @@
 ..
   This file is part of GNU TALER.
-  Copyright (C) 2014-2020 Taler Systems SA
+  Copyright (C) 2014-2021 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
@@ -172,6 +172,10 @@ possibly by using HTTPS.
 
   .. ts:def:: P2PFees
 
+    .. note::
+
+       This is a draft API that is not yet implemented.
+
     interface P2PFees {
 
       // What date (inclusive) does these fees go into effect?
@@ -1665,6 +1669,11 @@ denomination.
       // URL, or if the base URL has changed since the deposit.
       transaction_base_url?: string;
 
+      // Payment target that the merchant should
+      // use to check for its KYC status using
+      // the ``/kyc/$PAYMENT_TARGET_UUID`` endpoint.
+      payment_target_uuid: Integer;
+
       // Timestamp when the deposit was received by the exchange.
       exchange_timestamp: Timestamp;
 
@@ -2512,6 +2521,12 @@ typically also view the balance.)
   .. ts:def:: TrackTransactionResponse
 
     interface TrackTransactionResponse {
+
+      // Payment target that the merchant should
+      // use to check for its KYC status using
+      // the ``/kyc/$PAYMENT_TARGET_UUID`` endpoint.
+      payment_target_uuid: Integer;
+
       // Raw wire transfer identifier of the deposit.
       wtid: Base32;
 
@@ -2539,6 +2554,12 @@ typically also view the balance.)
   .. ts:def:: TrackTransactionAcceptedResponse
 
     interface TrackTransactionAcceptedResponse {
+
+      // Payment target that the merchant should
+      // use to check for its KYC status using
+      // the ``/kyc/$PAYMENT_TARGET_UUID`` endpoint.
+      payment_target_uuid: Integer;
+
       // Time by which the exchange currently thinks the deposit will be executed.
       execution_time: Timestamp;
     }
@@ -2649,6 +2670,11 @@ Refunds
 Wallet-to-wallet transfers
 --------------------------
 
+  .. note::
+
+     This is a draft API that is not yet implemented.
+
+
 .. http:GET:: /purses/$PURSE_PUB
 
   Obtain information about a purse. The request header must
@@ -3134,6 +3160,15 @@ Wallet-to-wallet transfers
       // public key used to create the signature.
       exchange_pub: EddsaPublicKey;
 
+      // Payment target that the recipient should
+      // use to check for its KYC status using
+      // the ``/kyc/$PAYMENT_TARGET_UUID`` endpoint.
+      //
+      // FIXME: may need to be a URL in case the
+      // exchange is foreign, alas, in this case
+      // we ALSO don't know the target UUID!
+      // => make optional?
+      payment_target_uuid: Integer;
     }
 
   .. ts:def:: MergeAccepted
@@ -3144,106 +3179,31 @@ Wallet-to-wallet transfers
       // under the given account.
       remaining_purses: Integer;
 
-    }
-
-
-.. http:POST:: /reserves/$RESERVE_PUB/kyc
-
-  Upgrade a reserve to an *account*.  The reserve must
-  (from wire transfers or merges of purses) already have a
-  sufficient balance to cover the KYC fee.  The signature
-  affirms that the KYC fee can and should be charged to the reserve.
-  The request always updates the payto URI associated with
-  the reserve, even if the KYC process fails or is not completed.
-
-  **Request:** The request body must be a `AccountSetupRequest` object.
-
-  :query timeout_ms=NUMBER: *Optional.*  If specified, the exchange will
-    wait up to ``timeout_ms`` milliseconds for the KYC gateway to
-    confirm completion of the KYC process.
-
-  **Response:**
-
-  :http:statuscode:`200 Ok`:
-    The operation succeeded, the exchange confirms that the account
-    can now be used.
-    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
-    request should be repeated.
-    The response will be an `AccountKycRedirect` object.
-  :http:statuscode:`504 Gateway Timeout`:
-    The exchange did not receive a confirmation from the KYC service
-    within the specified time period. Used when long-polling for the
-    result.
-
-  **Details:**
-
-  .. ts:def:: AccountSetupRequest
-
-     interface AccountSetupRequest {
-
-      // Time of the request to perform the KYC. Determines
-      // the KYC fee charged by the exchange. Must be
-      // reasonably close to the current time of the exchange.
-      kyc_timestamp: Timestamp;
-
-      // Bank account to be associated with the account.
-      // Can be 'payto://void/' to not associate the
-      // account with any bank account. In this case,
-      // closing the account will result in the balance
-      // being forfeit.  If the provided wire method is
-      // not supported by the exchange *and* not 'void',
-      // this is a ``Bad Request`` (HTTP status 400).
-      payto_uri: string;
-
-      // EdDSA signature of the reserve affirming the request
-      // to create the account, must be of purpose
-      // ``TALER_SIGNATURE_ACCOUNT_SETUP_REQUEST``
-      // and over `TALER_AccountSetupRequestSignaturePS`.
-      reserve_sig: EddsaPublicKey;
-
-    }
-
-  .. ts:def:: AccountKycStatus
-
-     interface AccountKycStatus {
-
-      // Current time of the exchange, used as part of
-      // what the exchange signs over.
-      now: Timestamp;
-
-      // EdDSA signature of the exchange affirming the account
-      // is KYC'ed, must be of purpose
-      // ``TALER_SIGNATURE_ACCOUNT_SETUP_SUCCESS``
-      // and over `TALER_AccountSetupRequestSignaturePS`.
-      exchange_sig: EddsaSignature;
-
-      // public key used to create the signature.
-      exchange_pub: EddsaPublicKey;
-    }
-
-  .. ts:def:: AccountKycRedirect
-
-     interface AccountKycRedirect {
-
-      // URL that the user should open in a browser to
-      // proceed with the KYC process.
-      kyc_url: string;
+      // Payment target that the recipient should
+      // use to check for its KYC status using
+      // the ``/kyc/$PAYMENT_TARGET_UUID`` endpoint.
+      //
+      // FIXME: may need to be a URL in case the
+      // exchange is foreign, alas, in this case
+      // we ALSO don't know the target UUID!
+      // => make optional?
+      payment_target_uuid: Integer;
 
     }
 
 
 
-
-
 .. _exchange_wads:
 
 
 Wads
 ^^^^
 
+  .. note::
+
+     This is a draft API that is not yet implemented.
+
+
 These endpoints are used to manage exchange-to-exchange payments in support of
 wallet-to-wallet payments.  Only another exchange should access this endpoint.
 
@@ -3330,3 +3290,73 @@ wallet-to-wallet payments.  Only another exchange should access this endpoint.
       // Wad fees that was charged to the purse.
       wad_fees: Amount;
     }
+
+
+------------------
+KYC status updates
+------------------
+
+  .. note::
+
+     This is a draft API that is not yet implemented.
+
+
+.. http:GET:: /kyc/$PAYMENT_TARGET_UUID
+
+  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 timeout_ms=NUMBER: *Optional.*  If specified, the exchange will
+    wait up to ``timeout_ms`` milliseconds for the KYC gateway to
+    confirm completion of the KYC process.
+
+
+  **Response:**
+
+  :http:statuscode:`200 Ok`:
+    The KYC operation succeeded, the exchange confirms that the
+    payment target will receive payments.
+    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
+    request should be repeated.
+    The response will be an `AccountKycRedirect` object.
+  :http:statuscode:`504 Gateway Timeout`:
+    The exchange did not receive a confirmation from the KYC service
+    within the specified time period. Used when long-polling for the
+    result.
+
+  **Details:**
+
+  .. ts:def:: AccountKycStatus
+
+     interface AccountKycStatus {
+
+      // Current time of the exchange, used as part of
+      // what the exchange signs over.
+      now: Timestamp;
+
+      // EdDSA signature of the exchange affirming the account
+      // is KYC'ed, must be of purpose
+      // ``TALER_SIGNATURE_ACCOUNT_SETUP_SUCCESS``
+      // and over `TALER_AccountSetupStatusSignaturePS`.
+      exchange_sig: EddsaSignature;
+
+      // public key used to create the signature.
+      exchange_pub: EddsaPublicKey;
+    }
+
+  .. ts:def:: AccountKycRedirect
+
+     interface AccountKycRedirect {
+
+      // URL that the user should open in a browser to
+      // proceed with the KYC process.
+      kyc_url: string;
+
+    }