taler-docs

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

post-kyc-import-EXTERN_PUB.rst (4653B)

      1 .. http:post:: /kyc-import/$EXTERN_PUB
      2 
      3   The ``/kyc-import/$EXTERN_PUB`` POST endpoint allows third parties to
      4   upload KYC/KYB data.  The ``$EXTERN_PUB`` is the public EdDSA key
      5   identifying the 3rd party encoded using Crockford base32 encoding.
      6 
      7   Clients should repeat this request (with some backoff) until it
      8   succeeds. The request is idempotent, so repeating it is always safe.
      9   The request may also be performed repeatedly for the same customer
     10   data (payto:// and/or account public key) with the same or different
     11   attributes, for example to provide additional attributes or to
     12   associate another account key pair with the same payto:// address.
     13   The primary identify for any customer is always the payto:// address.
     14 
     15   .. note::
     16 
     17     The exchange operator may internally notice that multiple payto://
     18     addresses actually refer to the same entity, but that is of no concern
     19     for clients of this endpoint.
     20 
     21   Provided attributes may include data of type ``FileUpload``. In those
     22   cases, the data may either be provided inline, or reference a previous
     23   bulk import (by hash) performed via a POST to ``/kyc-bulk/``.
     24   Bulk imports MUST always be performed before the import of attribute
     25   data referencing the bulk data.
     26 
     27   This endpoint was introduced in protocol **vIMPORT**.
     28 
     29   **Request:**
     30 
     31   The request body must be a `KycDataImportRequest` object.
     32 
     33   **Response:**
     34 
     35   :http:statuscode:`204 No Content`:
     36     The information was successfully uploaded.
     37   :http:statuscode:`400 Bad Request`:
     38     The request body is malformed or a parameter is invalid.
     39     This response comes with a standard `ErrorDetail` response with
     40     a code of ``TALER_EC_GENERIC_PARAMETER_MALFORMED``.
     41     The client should not repeat the request until its has been
     42     restarted (presumably with a fixed implementation).
     43   :http:statuscode:`403 Forbidden`:
     44     The provided signature is invalid for the request.
     45     This response comes with a standard `ErrorDetail` response with
     46     a code of ``TALER_EC_KYC_IMPORT_SIGNATURE_INVALID``.
     47     The client should not repeat the request until its has been
     48     restarted (presumably with a fixed implementation).
     49   :http:statuscode:`404 Not Found`:
     50     The ``$EXTERN_PUB`` is unknown to the exchange.
     51     This response comes with a standard `ErrorDetail` response.
     52     Possible error codes include
     53     ``TALER_EC_EXCHANGE_KYC_IMPORT_3RD_PARTY_UNKNOWN`` or
     54     ``TALER_EC_GENERIC_ENDPOINT_UNKNOWN``.
     55     The client should not repeat the request until its has been
     56     restarted (presumably with a new configuration).
     57   :http:statuscode:`413 Request Entity Too Large`:
     58     The body is too large. This failure should be logged on both
     59     ends. The request should not be repeated.
     60   :http:statuscode:`500 Internal Server Error`:
     61     The server experienced an internal error.
     62     This response comes with a standard `ErrorDetail` response.
     63     Possible error codes include
     64     ``TALER_EC_GENERIC_DB_STORE_FAILED``,
     65     ``TALER_EC_GENERIC_DB_INVARIANT_FAILURE``,
     66     ``TALER_EC_GENERIC_DB_SETUP_FAILED``, or
     67     ``TALER_EC_EXCHANGE_KYC_GENERIC_AML_LOGIC_BUG``.
     68     The request should be repeated with some exponential back-off,
     69     giving the server operator to address its internal issues.
     70 
     71   **Details:**
     72 
     73   .. ts:def:: KycDataImportRequest
     74 
     75      interface KycDataImportRequest {
     76 
     77       // KYC attribute data. The fields present
     78       // will depend on the 3rd party and the entity the data is about.
     79       // Details will thus completely depend on the business context.
     80       // However, it MUST include a form ID.
     81       // Furthermore, the exchange may impose specific
     82       // restrictions on importing KYC data based on the 3rd party
     83       // and the respective business agreement.
     84       attributes: CustomerKycAttributes;
     85 
     86       // Time when the attributes were obtained by the 3rd party.
     87       import_date: Timestamp;
     88 
     89       // payto-URI of the bank account (or theoretically wallet)
     90       // for which the KYC/KYB data was obtained.
     91       customer_payto: string;
     92 
     93       // Public key of the merchant backend instance (or wallet)
     94       // that should be associated with the KYC/KYB data.
     95       account_pub: EddsaPublicKey;
     96 
     97       // EdDSA signature of the 3rd party. Must be of
     98       // purpose ``TALER_SIGNATURE_EXTERN_KYC_IMPORT_BINDING``
     99       // and be made over the purpose header and the
    100       // SHA512 hash over the (normalized) JSON of ``attributes``
    101       // as well as the timestamp, SHA512 hash of the payto URI
    102       // and the merchant public key.
    103       // See `ExternKycDataImportBindingPS <TALER_ExternKycDataImportBindingPS>`
    104       // for details.
    105       extern_sig: EddsaSignature;
    106 
    107     }