GET /aml/$OFFICER_PUB/decisions

Request:

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.

This endpoint was introduced in this form in protocol v20.

Query Parameters:

• limit – 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).

• offset – Optional. Row number threshold, see delta for its interpretation. Defaults to INT64_MAX, namely the biggest row id possible in the database.

• h_payto – Optional. Account selector using the normalized payto URI. All matching accounts are returned if this filter is absent, otherwise only decisions for this account.

• active – Optional. If set to yes, only return active decisions, if no only decisions that have been superseded. Do not give (or use “all”) to see all decisions regardless of activity status.

• investigation – Optional. If set to yes, only return accounts that are under AML investigation, if no only accounts that are not under investigation. Do not give (or use “all”) to see all accounts regardless of investigation status.

Response:

200 OK:

The response will be an AmlDecisionsResponse message.

204 No content:

There are no matching AML records.

403 Forbidden:

The signature is invalid.

404 Not found:

The designated AML account is not known.

409 Conflict:

The designated AML account is not enabled.

Details:

interface AmlDecisionsResponse {

  // Array of AML decisions matching the query.
  records: AmlDecision[];
}

interface AmlDecision {

  // Which payto-address is this record about.
  // Identifies a GNU Taler wallet or an affected bank account.
  h_payto: NormalizedPaytoHash;

  // Full payto URL of the account that the decision is
  // about. Since protocol **v30** (rev 1).
  full_payto: string;

  // True if the underlying payto://-URI is for a wallet
  // Since protocol **v25**.
  is_wallet: boolean;

  // Row ID of the record.  Used to filter by offset.
  rowid: Integer;

  // Justification for the decision. NULL if none
  // is available.
  justification?: string;

  // When was the decision made?
  decision_time: Timestamp;

  // Free-form properties about the account.
  // Can be used to store properties such as PEP,
  // risk category, type of business, hits on
  // sanctions lists, etc.
  //
  // Passing a properties object overrides all
  // of the current properties for the AML account.
  properties?: AccountProperties;

  // What are the new rules?
  limits: LegitimizationRuleSet;

  // True if the account is under investigation by AML staff
  // after this decision.
  to_investigate: boolean;

  // True if this is the active decision for the
  // account.
  is_active: boolean;

}

// All fields in this object are optional. The actual
// properties collected depend fully on the discretion
// of the exchange operator;
// however, some common fields are standardized
// and thus described here.
interface AccountProperties {

  // True if this is a politically exposed account.
  // Rules for classifying accounts as politically
  // exposed are country-dependent.
  pep?: boolean;

  // True if this is a sanctioned account.
  // Rules for classifying accounts as sanctioned
  // are country-dependent.
  sanctioned?: boolean;

  // True if this is a high-risk account.
  // Rules for classifying accounts as at-risk
  // are exchange operator-dependent.
  high_risk?: boolean;

  // Business domain of the account owner.
  // The list of possible business domains is
  // operator- or country-dependent.
  business_domain?: string;

  // Is the client's account currently frozen?
  is_frozen?: boolean;

  // Was the client's account reported to the authorities?
  was_reported?: boolean;

}

interface LegitimizationRuleSet {

  // When does this set of rules expire and
  // we automatically transition to the successor
  // measure?
  expiration_time: Timestamp;

  // Name of the measure to apply when the expiration time is
  // reached.  If not set, we refer to the default
  // set of rules (and the default account state).
  successor_measure?: string;

  // Legitimization rules that are to be applied
  // to this account.
  rules: KycRule[];

  // Custom measures that KYC rules and the
  // successor_measure may refer to.
  custom_measures: { "$measure_name" : MeasureInformation; };

}

interface KycRule {

  // Type of operation to which the rule applies.
  //
  // Must be one of "WITHDRAW", "DEPOSIT",
  // (p2p) "MERGE", (wallet) "BALANCE",
  // (reserve) "CLOSE", "AGGREGATE",
  // "TRANSACTION" or "REFUND".
  operation_type: string;

  // Name of the configuration section this rule
  // originates from. Not available for all rules.
  // Primarily informational, but also useful to
  // explicitly manipulate rules by-name in AML programs.
  rule_name?: string;

  // The measures will be taken if the given
  // threshold is crossed over the given timeframe.
  threshold: Amount;

  // Over which duration should the threshold be
  // computed.  All amounts of the respective
  // operation_type will be added up for this
  // duration and the sum compared to the threshold.
  timeframe: RelativeTime;

  // Array of names of measures to apply.
  // Names listed can be original measures or
  // custom measures from the AmlOutcome.
  // A special measure "verboten" is used if the
  // threshold may never be crossed.
  measures: string[];

  // If multiple rules apply to the same account
  // at the same time, the number with the highest
  // rule determines which set of measures will
  // be activated and thus become visible for the
  // user.
  display_priority: Integer;

  // True if the rule (specifically, operation_type,
  // threshold, timeframe) and the general nature of
  // the measures (verboten or approval required)
  // should be exposed to the client.
  // Defaults to "false" if not set.
  exposed?: boolean;

  // True if all the measures will eventually need to
  // be satisfied, false if any of the measures should
  // do.  Primarily used by the SPA to indicate how
  // the measures apply when showing them to the user;
  // in the end, AML programs will decide after each
  // measure what to do next.
  // Default (if missing) is false.
  is_and_combinator?: boolean;

}