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