taler-docs

commit e44df44939386f5443aaea144e8870b3e8cc77f1
parent 210d3f27b6c6619fb02e20b7cd15ee3d237a0859
Author: Christian Grothoff <christian@grothoff.org>
Date:   Thu,  2 Feb 2023 14:56:14 +0100

slight rework of KYC/AML decision inspection API

Diffstat:
M
core/api-common.rst
 | 
12
++++++++++++
M
core/api-exchange.rst
 | 
39
+++++++++++++++++++++++++--------------

2 files changed, 37 insertions(+), 14 deletions(-)
diff --git a/core/api-common.rst b/core/api-common.rst
@@ -694,6 +694,18 @@ uses 512-bit hash codes (64 bytes).
      uint8_t ecdhe_priv[32];
    };
 
+
+.. _officer-pub:
+.. sourcecode:: c
+
+   struct TALER_AmlOfficerPublicKeyP {
+     uint8_t eddsa_pub[32];
+   };
+
+   struct TALER_AmlOfficerPrivateKeyP {
+     uint8_t eddsa_priv[32];
+   };
+
 .. _sign-key-pub:
 .. sourcecode:: c
 
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
@@ -1219,15 +1219,12 @@ to allow exchange staff to monitor suspicious transactions
 and freeze or unfreeze accounts suspected of money laundering.
 
 
-.. http:get:: /aml/$OFFICER_PUB/decisions
+.. http:get:: /aml/$OFFICER_PUB/decisions/$STATE
 
-  Obtain list of AML decisions (typically filtered).
+  Obtain list of AML decisions (filtered by $STATE).  ``$STATE`` must be either ``normal``, ``pending`` or ``frozen``.
 
-  *AML-Officer-Signature*: The client must provide Base-32 encoded EdDSA signature with ``$OFFICER_PRIV``, affirming the desire to obtain AML data.  Note that this is merely a simple authentication mechanism, the details of the request are not protected by the signature.
+  *Taler-AML-Officer-Signature*: The client must provide Base-32 encoded EdDSA signature with ``$OFFICER_PRIV``, affirming the desire to obtain AML data.  Note that this is merely a simple authentication mechanism, the details of the request are not protected by the signature.
 
-  :query frozen: *Optional*. If set to yes, only return frozen AML records.
-  :query pending: *Optional*. If set to yes, only return AML records where the decision is pending.
-  :query normal: *Optional*. If set to yes, only return AML records where transactions are allowed.
   :query delta: *Optional*. takes value of the form ``N (-N)``, so that at most ``N`` values strictly older (younger) than ``start`` are returned.  Defaults to ``-20`` to return the last 20 entries (before ``start``).
   :query start: *Optional*. Row number threshold, see ``delta`` for its interpretation.  Defaults to ``INT64_MAX``, namely the biggest row id possible in the database.
 
@@ -1269,8 +1266,11 @@ and freeze or unfreeze accounts suspected of money laundering.
       // What is the current AML state.
       current_state: Integer;
 
-      // When was the last decision made?
-      last_decision_time: Timestamp;
+      // Monthly transaction threshold before a review will be triggered
+      threshold: Amount;
+
+      // Row ID of the decision
+      rowid: Integer;
 
     }
 
@@ -1279,7 +1279,7 @@ and freeze or unfreeze accounts suspected of money laundering.
 
   Obtain deails about an AML decision.
 
-  *AML-Officer-Signature*: The client must provide Base-32 encoded EdDSA signature with ``$OFFICER_PRIV``, affirming the desire to obtain AML data.  Note that this is merely a simple authentication mechanism, the details of the request are not protected by the signature.
+  *Taler-AML-Officer-Signature*: The client must provide Base-32 encoded EdDSA signature with ``$OFFICER_PRIV``, affirming the desire to obtain AML data.  Note that this is merely a simple authentication mechanism, the details of the request are not protected by the signature.
 
   :query history: *Optional*. If set to yes, we return all historic decisions and not only the last one.
 
@@ -1309,10 +1309,10 @@ and freeze or unfreeze accounts suspected of money laundering.
       // Array of AML decisions made for this account. Possibly
       // contains only the most recent decision if "history" was
       // not set to 'true'.
-      aml_records: AmlDecisionDetail[];
+      aml_history: AmlDecisionDetail[];
 
-      // Array of KYC records obtained for this account.
-      kyc_records: KycDetail[];
+      // Array of KYC attributes obtained for this account.
+      kyc_attributes: KycDetail[];
     }
 
   .. ts:def:: AmlDecisionDetail
@@ -1328,6 +1328,12 @@ and freeze or unfreeze accounts suspected of money laundering.
       // When was this decision made?
       decision_time: Timestamp;
 
+      // What is the new AML decision threshold (in monthly transaction volume)?
+      new_threshold: Amount;
+
+      // Who made the decision?
+      decider_pub: TALER_AmlOfficerPublicKeyP;
+
     }
 
   .. ts:def:: KycDetail
@@ -1338,12 +1344,17 @@ and freeze or unfreeze accounts suspected of money laundering.
       // which was used to collect the KYC details
       provider_section: string;
 
-      // The collected KYC data.
-      attributes: Object;
+      // The collected KYC data.  NULL if the attribute data could not
+      // be decrypted (internal error of the exchange, likely the
+      // attribute key was changed).
+      attributes?: Object;
 
       // Time when the KYC data was collected
       collection_time: Timestamp;
 
+      // Time when the validity of the KYC data will expire
+      expiration_time: Timestamp;
+
     }