get-aml-OFFICER_PUB-decisions.rst (8152B)
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 // When was the decision made? 96 decision_time: Timestamp; 97 98 // Free-form properties about the account. 99 // Can be used to store properties such as PEP, 100 // risk category, type of business, hits on 101 // sanctions lists, etc. 102 // 103 // Passing a properties object overrides all 104 // of the current properties for the AML account. 105 properties?: AccountProperties; 106 107 // What are the new rules? 108 limits: LegitimizationRuleSet; 109 110 // True if the account is under investigation by AML staff 111 // after this decision. 112 to_investigate: boolean; 113 114 // True if this is the active decision for the 115 // account. 116 is_active: boolean; 117 118 } 119 120 .. ts:def:: AccountProperties 121 122 // All fields in this object are optional. The actual 123 // properties collected depend fully on the discretion 124 // of the exchange operator; 125 // however, some common fields are standardized 126 // and thus described here. 127 interface AccountProperties { 128 129 // True if this is a politically exposed account. 130 // Rules for classifying accounts as politically 131 // exposed are country-dependent. 132 pep?: boolean; 133 134 // True if this is a sanctioned account. 135 // Rules for classifying accounts as sanctioned 136 // are country-dependent. 137 sanctioned?: boolean; 138 139 // True if this is a high-risk account. 140 // Rules for classifying accounts as at-risk 141 // are exchange operator-dependent. 142 high_risk?: boolean; 143 144 // Business domain of the account owner. 145 // The list of possible business domains is 146 // operator- or country-dependent. 147 business_domain?: string; 148 149 // Is the client's account currently frozen? 150 is_frozen?: boolean; 151 152 // Was the client's account reported to the authorities? 153 was_reported?: boolean; 154 155 } 156 157 .. ts:def:: LegitimizationRuleSet 158 159 interface LegitimizationRuleSet { 160 161 // When does this set of rules expire and 162 // we automatically transition to the successor 163 // measure? 164 expiration_time: Timestamp; 165 166 // Name of the measure to apply when the expiration time is 167 // reached. If not set, we refer to the default 168 // set of rules (and the default account state). 169 successor_measure?: string; 170 171 // Legitimization rules that are to be applied 172 // to this account. 173 rules: KycRule[]; 174 175 // Custom measures that KYC rules and the 176 // ``successor_measure`` may refer to. 177 custom_measures: { "$measure_name" : MeasureInformation; }; 178 179 } 180 181 .. ts:def:: KycRule 182 183 interface KycRule { 184 185 // Type of operation to which the rule applies. 186 // 187 // Must be one of "WITHDRAW", "DEPOSIT", 188 // (p2p) "MERGE", (wallet) "BALANCE", 189 // (reserve) "CLOSE", "AGGREGATE", 190 // "TRANSACTION" or "REFUND". 191 operation_type: string; 192 193 // Name of the configuration section this rule 194 // originates from. Not available for all rules. 195 // Primarily informational, but also useful to 196 // explicitly manipulate rules by-name in AML programs. 197 rule_name?: string; 198 199 // The measures will be taken if the given 200 // threshold is crossed over the given timeframe. 201 threshold: Amount; 202 203 // Over which duration should the ``threshold`` be 204 // computed. All amounts of the respective 205 // ``operation_type`` will be added up for this 206 // duration and the sum compared to the ``threshold``. 207 timeframe: RelativeTime; 208 209 // Array of names of measures to apply. 210 // Names listed can be original measures or 211 // custom measures from the `AmlOutcome`. 212 // A special measure "verboten" is used if the 213 // threshold may never be crossed. 214 measures: string[]; 215 216 // If multiple rules apply to the same account 217 // at the same time, the number with the highest 218 // rule determines which set of measures will 219 // be activated and thus become visible for the 220 // user. 221 display_priority: Integer; 222 223 // True if the rule (specifically, operation_type, 224 // threshold, timeframe) and the general nature of 225 // the measures (verboten or approval required) 226 // should be exposed to the client. 227 // Defaults to "false" if not set. 228 exposed?: boolean; 229 230 // True if all the measures will eventually need to 231 // be satisfied, false if any of the measures should 232 // do. Primarily used by the SPA to indicate how 233 // the measures apply when showing them to the user; 234 // in the end, AML programs will decide after each 235 // measure what to do next. 236 // Default (if missing) is false. 237 is_and_combinator?: boolean; 238 239 }