get-aml-OFFICER_PUB-decisions.rst (8148B)
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 - The ``$H_OFFICER_PUB`` path segment is malformed. 44 This response comes with a standard `ErrorDetail` response with 45 a code of ``TALER_EC_GENERIC_PATH_SEGMENT_MALFORMED``. 46 - The required HTTP header with the signature is missing. Returned with 47 ``TALER_EC_GENERIC_HTTP_HEADERS_MALFORMED``. 48 :http:statuscode:`403 Forbidden`: 49 Two cases: 50 - The signature is invalid. Returned with a code of 51 ``TALER_EC_EXCHANGE_GENERIC_AML_OFFICER_GET_SIGNATURE_INVALID``. 52 - The specific officer is unknown or disabled. Returned with a code of 53 ``TALER_EC_EXCHANGE_GENERIC_AML_OFFICER_ACCESS_DENIED``. 54 :http:statuscode:`500 Internal server error`: 55 The server had an internal problem handling the request. 56 The error code is usually a ``TALER_EC_GENERIC_DB_FETCH_FAILED``. 57 58 **Details:** 59 60 .. ts:def:: AmlDecisionsResponse 61 62 interface AmlDecisionsResponse { 63 64 // Array of AML decisions matching the query. 65 records: AmlDecision[]; 66 } 67 68 .. ts:def:: AmlDecision 69 70 interface AmlDecision { 71 72 // Which payto-address is this record about. 73 // Identifies a GNU Taler wallet or an affected bank account. 74 h_payto: NormalizedPaytoHash; 75 76 // Full payto URL of the account that the decision is 77 // about. Since protocol **v30** (rev 1). 78 full_payto: string; 79 80 // True if the underlying payto://-URI is for a wallet 81 // Since protocol **v25**. 82 is_wallet: boolean; 83 84 // Row ID of the record. Used to filter by offset. 85 rowid: Integer; 86 87 // Justification for the decision. NULL if none 88 // is available. 89 justification?: string; 90 91 // When was the decision made? 92 decision_time: Timestamp; 93 94 // Free-form properties about the account. 95 // Can be used to store properties such as PEP, 96 // risk category, type of business, hits on 97 // sanctions lists, etc. 98 // 99 // Passing a properties object overrides all 100 // of the current properties for the AML account. 101 properties?: AccountProperties; 102 103 // What are the new rules? 104 limits: LegitimizationRuleSet; 105 106 // True if the account is under investigation by AML staff 107 // after this decision. 108 to_investigate: boolean; 109 110 // True if this is the active decision for the 111 // account. 112 is_active: boolean; 113 114 } 115 116 .. ts:def:: AccountProperties 117 118 // All fields in this object are optional. The actual 119 // properties collected depend fully on the discretion 120 // of the exchange operator; 121 // however, some common fields are standardized 122 // and thus described here. 123 interface AccountProperties { 124 125 // True if this is a politically exposed account. 126 // Rules for classifying accounts as politically 127 // exposed are country-dependent. 128 pep?: boolean; 129 130 // True if this is a sanctioned account. 131 // Rules for classifying accounts as sanctioned 132 // are country-dependent. 133 sanctioned?: boolean; 134 135 // True if this is a high-risk account. 136 // Rules for classifying accounts as at-risk 137 // are exchange operator-dependent. 138 high_risk?: boolean; 139 140 // Business domain of the account owner. 141 // The list of possible business domains is 142 // operator- or country-dependent. 143 business_domain?: string; 144 145 // Is the client's account currently frozen? 146 is_frozen?: boolean; 147 148 // Was the client's account reported to the authorities? 149 was_reported?: boolean; 150 151 } 152 153 .. ts:def:: LegitimizationRuleSet 154 155 interface LegitimizationRuleSet { 156 157 // When does this set of rules expire and 158 // we automatically transition to the successor 159 // measure? 160 expiration_time: Timestamp; 161 162 // Name of the measure to apply when the expiration time is 163 // reached. If not set, we refer to the default 164 // set of rules (and the default account state). 165 successor_measure?: string; 166 167 // Legitimization rules that are to be applied 168 // to this account. 169 rules: KycRule[]; 170 171 // Custom measures that KYC rules and the 172 // ``successor_measure`` may refer to. 173 custom_measures: { "$measure_name" : MeasureInformation; }; 174 175 } 176 177 .. ts:def:: KycRule 178 179 interface KycRule { 180 181 // Type of operation to which the rule applies. 182 // 183 // Must be one of "WITHDRAW", "DEPOSIT", 184 // (p2p) "MERGE", (wallet) "BALANCE", 185 // (reserve) "CLOSE", "AGGREGATE", 186 // "TRANSACTION" or "REFUND". 187 operation_type: string; 188 189 // Name of the configuration section this rule 190 // originates from. Not available for all rules. 191 // Primarily informational, but also useful to 192 // explicitly manipulate rules by-name in AML programs. 193 rule_name?: string; 194 195 // The measures will be taken if the given 196 // threshold is crossed over the given timeframe. 197 threshold: Amount; 198 199 // Over which duration should the ``threshold`` be 200 // computed. All amounts of the respective 201 // ``operation_type`` will be added up for this 202 // duration and the sum compared to the ``threshold``. 203 timeframe: RelativeTime; 204 205 // Array of names of measures to apply. 206 // Names listed can be original measures or 207 // custom measures from the `AmlOutcome`. 208 // A special measure "verboten" is used if the 209 // threshold may never be crossed. 210 measures: string[]; 211 212 // If multiple rules apply to the same account 213 // at the same time, the number with the highest 214 // rule determines which set of measures will 215 // be activated and thus become visible for the 216 // user. 217 display_priority: Integer; 218 219 // True if the rule (specifically, operation_type, 220 // threshold, timeframe) and the general nature of 221 // the measures (verboten or approval required) 222 // should be exposed to the client. 223 // Defaults to "false" if not set. 224 exposed?: boolean; 225 226 // True if all the measures will eventually need to 227 // be satisfied, false if any of the measures should 228 // do. Primarily used by the SPA to indicate how 229 // the measures apply when showing them to the user; 230 // in the end, AML programs will decide after each 231 // measure what to do next. 232 // Default (if missing) is false. 233 is_and_combinator?: boolean; 234 235 }