taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

post-aml-OFFICER_PUB-decision.rst (4483B)

      1 .. http:post:: /aml/$OFFICER_PUB/decision
      2 
      3   Make an AML decision. Triggers the respective action and
      4   records the justification.
      5 
      6   **Request:**
      7 
      8   The request must be an `AmlDecisionRequest` message.
      9 
     10   **Response**
     11 
     12   :http:statuscode:`204 No content`:
     13     The AML decision has been executed and recorded successfully.
     14   :http:statuscode:`400 Bad request`:
     15     The request was malformed.
     16     This response comes with a standard `ErrorDetail` response with
     17     a code of ``TALER_EC_GENERIC_PARAMETER_MALFORMED``.
     18   :http:statuscode:`403 Forbidden`:
     19     The signature is invalid (or the AML officer not known).
     20     Returned with an error code of
     21     ``TALER_EC_EXCHANGE_AML_DECISION_ADD_SIGNATURE_INVALID`` or
     22     ``TALER_EC_EXCHANGE_GENERIC_AML_OFFICER_ACCESS_DENIED``.
     23   :http:statuscode:`404 Not found`:
     24     The normalized payto-address the decision was made for is unknown to the exchange.
     25     Returned with an error code of:
     26     ``TALER_EC_EXCHANGE_GENERIC_BANK_ACCOUNT_UNKNOWN``
     27   :http:statuscode:`409 Conflict`:
     28     The designated AML account is not enabled or a more recent
     29     decision was already submitted.
     30     Returned with an error code of:
     31 
     32     - ``TALER_EC_EXCHANGE_AML_DECISION_MORE_RECENT_PRESENT`` or
     33     - ``TALER_EC_EXCHANGE_AML_DECISION_INVALID_OFFICER``
     34   :http:statuscode:`413 Request entity too large`:
     35     The uploaded body is to long, it exceeds the size limit.
     36     Returned with an error code of
     37     ``TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT``.
     38   :http:statuscode:`500 Internal server error`:
     39     The server had an internal error processing the request.
     40     Returned with one of various error codes, including:
     41 
     42     - ``TALER_EC_EXCHANGE_KYC_GENERIC_AML_LOGIC_BUG``
     43     - ``TALER_EC_GENERIC_DB_STORE_FAILED``
     44     - ``TALER_EC_EXCHANGE_KYC_RECURSIVE_RULE_DETECTED``
     45     - ``TALER_EC_GENERIC_DB_FETCH_FAILED``
     46     - ``TALER_EC_GENERIC_DB_COMMIT_FAILED``
     47     - ``TALER_EC_EXCHANGE_KYC_AML_PROGRAM_FAILURE``
     48     - ``TALER_EC_GENERIC_INTERNAL_INVARIANT_FAILURE``
     49     - ``TALER_EC_EXCHANGE_GENERIC_KYC_FALLBACK_FAILED``
     50     - ``TALER_EC_EXCHANGE_KYC_AML_PROGRAM_MALFORMED_RESULT``
     51     - ``TALER_EC_EXCHANGE_GENERIC_KYC_FALLBACK_UNKNOWN``
     52 
     53   **Details:**
     54 
     55   .. ts:def:: AmlDecisionRequest
     56 
     57     interface AmlDecisionRequest {
     58 
     59       // Human-readable justification for the decision.
     60       justification: string;
     61 
     62       // Hash of normalized payto-address of the account the decision is about.
     63       // Identifies a GNU Taler wallet or an affected bank account.
     64       h_payto: NormalizedPaytoHash;
     65 
     66       // Full payto address of the account the decision is about.
     67       // Optional. Must be given if the account is not yet
     68       // known to the exchange. If given, must match ``h_payto``
     69       // (when normalized and then hashed).
     70       // @since protocol **v21**.
     71       payto_uri?: string;
     72 
     73       // What are the new rules?
     74       // New since protocol **v20**.
     75       new_rules: LegitimizationRuleSet;
     76 
     77       // What are the new account properties?
     78       // New since protocol **v20**.
     79       properties?: AccountProperties;
     80 
     81       // Array of AML/KYC events to trigger for statistics.
     82       // Note that this information is not covered by the signature
     83       // (which is OK as events are just for statistics).
     84       // New since protocol **v24**.
     85       events?: string[];
     86 
     87       // Space-separated list of measures to trigger
     88       // immediately on the account.
     89       // Prefixed with a "+" to indicate that the
     90       // measures should be ANDed.
     91       // Should typically be used to give the user some
     92       // information or request additional information.
     93       //
     94       // At most one measure with a SKIP check may be specified.
     95       //
     96       // @since protocol **v21**.
     97       new_measures?: string;
     98 
     99       // True if the account should remain under investigation by AML staff.
    100       // @since protocol **v20**.
    101       keep_investigating: boolean;
    102 
    103       // Signature by the AML officer over a `TALER_AmlDecisionPS`.
    104       // Must have purpose ``TALER_SIGNATURE_MASTER_AML_KEY``.
    105       officer_sig: EddsaSignature;
    106 
    107       // When was the decision made?
    108       decision_time: Timestamp;
    109 
    110       // KYC attributes uploaded by the AML officer
    111       // The object *must* contain high-entropy salt,
    112       // as the hash of the attributes will be
    113       // stored in plain text.
    114       attributes?: CustomerKycAttributes;
    115 
    116       // Expiration timestamp of the attributes.
    117       // Mandatory if attributes are present.
    118       attributes_expiration?: Timestamp;
    119 
    120     }