get-aml-OFFICER_PUB-decisions.rst (9012B)
1 .. http:get:: /aml/$OFFICER_PUB/decisions 2 3 **Request:** 4 5 *Taler-AML-Officer-Signature*: 6 The client must provide Base-32 encoded EdDSA signature with 7 ``$OFFICER_PRIV``, affirming the desire to obtain AML data. Note that 8 this is merely a simple authentication mechanism, the details of the 9 request are not protected by the signature. 10 11 This endpoint was introduced in this form in protocol **v20**. 12 13 :query limit: 14 *Optional*. takes value of the form ``N (-N)``, so that at 15 most ``N`` values strictly older (younger) than ``start`` are returned. 16 Defaults to ``-20`` to return the last 20 entries (before ``start``). 17 :query offset: 18 *Optional*. Row number threshold, see ``delta`` for its 19 interpretation. Defaults to ``INT64_MAX``, namely the biggest row id 20 possible in the database. 21 :query h_payto: 22 *Optional*. Account selector using the *normalized* payto URI. 23 All matching accounts are returned if this 24 filter is absent, otherwise only decisions for this account. 25 :query active: 26 *Optional*. If set to yes, only return active decisions, if no only 27 decisions that have been superseded. Do not give (or use "all") to 28 see all decisions regardless of activity status. 29 :query investigation: 30 *Optional*. If set to yes, only return accounts that are under 31 AML investigation, if no only accounts that are not under investigation. 32 Do not give (or use "all") to see all accounts regardless of 33 investigation status. 34 35 **Response:** 36 37 :http:statuscode:`200 OK`: 38 The response will be an `AmlDecisionsResponse` message. 39 :http:statuscode:`204 No content`: 40 There are no matching AML records. 41 :http:statuscode:`400 Bad Request`: 42 The request is malformed. Cases include: 43 44 - The ``$H_OFFICER_PUB`` path segment is malformed. 45 This response comes with a standard `ErrorDetail` response with 46 a code of ``TALER_EC_GENERIC_PATH_SEGMENT_MALFORMED``. 47 - The required HTTP header with the signature is missing. Returned with 48 ``TALER_EC_GENERIC_HTTP_HEADERS_MALFORMED``. 49 50 :http:statuscode:`403 Forbidden`: 51 Two cases: 52 53 - The signature is invalid. Returned with a code of 54 ``TALER_EC_EXCHANGE_GENERIC_AML_OFFICER_GET_SIGNATURE_INVALID``. 55 - The specific officer is unknown or disabled. Returned with a code of 56 ``TALER_EC_EXCHANGE_GENERIC_AML_OFFICER_ACCESS_DENIED``. 57 58 :http:statuscode:`500 Internal server error`: 59 The server had an internal problem handling the request. 60 The error code is usually a ``TALER_EC_GENERIC_DB_FETCH_FAILED``. 61 62 **Details:** 63 64 .. ts:def:: AmlDecisionsResponse 65 66 interface AmlDecisionsResponse { 67 68 // Array of AML decisions matching the query. 69 records: AmlDecision[]; 70 } 71 72 .. ts:def:: AmlDecision 73 74 interface AmlDecision { 75 76 // Which payto-address is this record about. 77 // Identifies a GNU Taler wallet or an affected bank account. 78 h_payto: NormalizedPaytoHash; 79 80 // Full payto URL of the account that the decision is 81 // about. Since protocol **v30** (rev 1). 82 full_payto: string; 83 84 // True if the underlying payto://-URI is for a wallet 85 // Since protocol **v25**. 86 is_wallet: boolean; 87 88 // Row ID of the record. Used to filter by offset. 89 rowid: Integer; 90 91 // Justification for the decision. NULL if none 92 // is available. 93 justification?: string; 94 95 // Space-separated names of measures that the decision requested 96 // immediately. A leading "+" means all listed measures are required; 97 // otherwise satisfying any one of them is sufficient. Missing if the 98 // decision did not request an immediate measure. 99 new_measures?: string; 100 101 // Public key of the AML officer who made the decision. Missing for 102 // automated outcomes and for old records without provenance. 103 decider_pub?: EddsaPublicKey; 104 105 // Human-readable name of the AML officer as it was configured when the 106 // decision was made. Missing for automated outcomes or if unavailable. 107 decider_name?: string; 108 109 // Row ID of customer information submitted as part of this decision. 110 // Missing if the decision did not add customer information. 111 kyc_attributes_rowid?: Integer; 112 113 // When was the decision made? 114 decision_time: Timestamp; 115 116 // Free-form properties about the account. 117 // Can be used to store properties such as PEP, 118 // risk category, type of business, hits on 119 // sanctions lists, etc. 120 // 121 // Passing a properties object overrides all 122 // of the current properties for the AML account. 123 properties?: AccountProperties; 124 125 // What are the new rules? 126 limits: LegitimizationRuleSet; 127 128 // True if the account is under investigation by AML staff 129 // after this decision. 130 to_investigate: boolean; 131 132 // True if this is the active decision for the 133 // account. 134 is_active: boolean; 135 136 } 137 138 .. ts:def:: AccountProperties 139 140 // All fields in this object are optional. The actual 141 // properties collected depend fully on the discretion 142 // of the exchange operator; 143 // however, some common fields are standardized 144 // and thus described here. 145 interface AccountProperties { 146 147 // True if this is a politically exposed account. 148 // Rules for classifying accounts as politically 149 // exposed are country-dependent. 150 pep?: boolean; 151 152 // True if this is a sanctioned account. 153 // Rules for classifying accounts as sanctioned 154 // are country-dependent. 155 sanctioned?: boolean; 156 157 // True if this is a high-risk account. 158 // Rules for classifying accounts as at-risk 159 // are exchange operator-dependent. 160 high_risk?: boolean; 161 162 // Business domain of the account owner. 163 // The list of possible business domains is 164 // operator- or country-dependent. 165 business_domain?: string; 166 167 // Is the client's account currently frozen? 168 is_frozen?: boolean; 169 170 // Was the client's account reported to the authorities? 171 was_reported?: boolean; 172 173 } 174 175 .. ts:def:: LegitimizationRuleSet 176 177 interface LegitimizationRuleSet { 178 179 // When does this set of rules expire and 180 // we automatically transition to the successor 181 // measure? 182 expiration_time: Timestamp; 183 184 // Name of the measure to apply when the expiration time is 185 // reached. If not set, we refer to the default 186 // set of rules (and the default account state). 187 successor_measure?: string; 188 189 // Legitimization rules that are to be applied 190 // to this account. 191 rules: KycRule[]; 192 193 // Custom measures that KYC rules and the 194 // ``successor_measure`` may refer to. 195 custom_measures: { "$measure_name" : MeasureInformation; }; 196 197 } 198 199 .. ts:def:: KycRule 200 201 interface KycRule { 202 203 // Type of operation to which the rule applies. 204 // 205 // Must be one of "WITHDRAW", "DEPOSIT", 206 // (p2p) "MERGE", (wallet) "BALANCE", 207 // (reserve) "CLOSE", "AGGREGATE", 208 // "TRANSACTION" or "REFUND". 209 operation_type: string; 210 211 // Name of the configuration section this rule 212 // originates from. Not available for all rules. 213 // Primarily informational, but also useful to 214 // explicitly manipulate rules by-name in AML programs. 215 rule_name?: string; 216 217 // The measures will be taken if the given 218 // threshold is crossed over the given timeframe. 219 threshold: Amount; 220 221 // Over which duration should the ``threshold`` be 222 // computed. All amounts of the respective 223 // ``operation_type`` will be added up for this 224 // duration and the sum compared to the ``threshold``. 225 timeframe: RelativeTime; 226 227 // Array of names of measures to apply. 228 // Names listed can be original measures or 229 // custom measures from the `AmlOutcome`. 230 // A special measure "verboten" is used if the 231 // threshold may never be crossed. 232 measures: string[]; 233 234 // If multiple rules apply to the same account 235 // at the same time, the number with the highest 236 // rule determines which set of measures will 237 // be activated and thus become visible for the 238 // user. 239 display_priority: Integer; 240 241 // True if the rule (specifically, operation_type, 242 // threshold, timeframe) and the general nature of 243 // the measures (verboten or approval required) 244 // should be exposed to the client. 245 // Defaults to "false" if not set. 246 exposed?: boolean; 247 248 // True if all the measures will eventually need to 249 // be satisfied, false if any of the measures should 250 // do. Primarily used by the SPA to indicate how 251 // the measures apply when showing them to the user; 252 // in the end, AML programs will decide after each 253 // measure what to do next. 254 // Default (if missing) is false. 255 is_and_combinator?: boolean; 256 257 }