taler-docs

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

get-kyc-info-ACCESS_TOKEN.rst (4398B)

      1 .. http:get:: /kyc-info/$ACCESS_TOKEN
      2 
      3   The ``/kyc-info/$ACCESS_TOKEN`` endpoints are created per client
      4   account hash (but access controlled via a unique target token)
      5   to return information about the state of the KYC or AML process
      6   to the KYC SPA.  The SPA uses this information to show the user an
      7   appropriate dialog. The SPA should also long-poll this endpoint for changes
      8   to the AML/KYC state. Note that this is a client-facing endpoint, so it will
      9   only provide a restricted amount of information to the customer (as some
     10   laws may forbid us to inform particular customers about their true status).
     11   The endpoint will typically inform the SPA about possible choices to
     12   proceed, such as directly uploading files, contacting AML staff, or
     13   proceeding with a particular KYC process at an external provider (such as
     14   Challenger).  If the user chooses to initate a KYC process at an external
     15   provider, the SPA must request the respective process to be set-up by the
     16   exchange via the ``/kyc-start/`` endpoint.
     17 
     18   This endpoint was introduced in protocol **v20**.
     19 
     20   **Request:**
     21 
     22   *If-None-Match*:
     23     The client MAY provide an ``If-None-Match`` header with an ETag.
     24 
     25   :query timeout_ms=MILLISECONDS:
     26     *Optional.* If specified, the exchange will wait up to MILLISECONDS for
     27     a change to a more recent legitimization measure before returning a 304
     28     Not Modified status.
     29 
     30   **Response:**
     31 
     32   *Etag*: Will be set to a compound of the legitimization measure and outcome serial IDs, in the format ``"<measure_row>-<outcome_row>"``. Used for long-polling (only for 200 OK responses).
     33 
     34   :http:statuscode:`200 OK`:
     35     The body is a `KycProcessClientInformation`.
     36   :http:statuscode:`202 Accepted`:
     37     The exchange is currently processing the KYC status. The request should be
     38     repeated later again.
     39   :http:statuscode:`204 No Content`:
     40     There are no open KYC requirements or possible voluntary checks
     41     the client might perform.
     42   :http:statuscode:`304 Not Modified`:
     43     The KYC requirements did not change.
     44   :http:statuscode:`400 Bad Request`:
     45     The ``$ACCESS_TOKEN`` is malformed.
     46     This response comes with a standard `ErrorDetail` response with
     47     a code of ``TALER_EC_GENERIC_PARAMETER_MALFORMED``.
     48   :http:statuscode:`403 Forbidden`:
     49     The access token is invalid or the account is not authorized.
     50     This response comes with a standard `ErrorDetail` response with
     51     a code of ``TALER_EC_EXCHANGE_KYC_INFO_AUTHORIZATION_FAILED``.
     52   :http:statuscode:`500 Internal Server Error`:
     53     The server experienced an internal error.
     54     This response comes with a standard `ErrorDetail` response with
     55     a code of ``TALER_EC_GENERIC_DB_FETCH_FAILED``,
     56     ``TALER_EC_GENERIC_DB_STORE_FAILED``,
     57     ``TALER_EC_GENERIC_DB_COMMIT_FAILED``, or
     58     ``TALER_EC_GENERIC_DB_INVARIANT_FAILURE``.
     59 
     60 
     61   **Details:**
     62 
     63   .. ts:def:: KycProcessClientInformation
     64 
     65     interface KycProcessClientInformation {
     66 
     67       // Array of requirements.
     68       requirements: KycRequirementInformation[];
     69 
     70       // True if the client is expected to eventually satisfy all requirements.
     71       // Default (if missing) is false.
     72       is_and_combinator?: boolean
     73 
     74       // List of available voluntary checks the client could undertake.
     75       // @since protocol **vATTEST**.
     76       voluntary_measures?: KycRequirementInformation[];
     77     }
     78 
     79   .. ts:def:: KycRequirementInformation
     80 
     81     interface KycRequirementInformation {
     82 
     83       // Which form should be used? Common values include "INFO"
     84       // (to just show the descriptions but allow no action),
     85       // "LINK" (to enable the user to obtain a link via
     86       // ``/kyc-start/``) or any build-in form name supported
     87       // by the SPA.
     88       form: string;
     89 
     90       // Object with arbitrary additional context, completely depends on
     91       // the specific form.
     92       context?: Object;
     93 
     94       // English description of the requirement.
     95       description: string;
     96 
     97       // Map from IETF BCP 47 language tags to localized
     98       // description texts.
     99       description_i18n ?: { [lang_tag: string]: string };
    100 
    101       // ID of the requirement, useful to construct the
    102       // ``/kyc-upload/$ID`` or ``/kyc-start/$ID`` endpoint URLs.
    103       // Present if and only if "form" is not "INFO".  The
    104       // ``$ID`` value may itself contain ``/`` or ``?`` and
    105       // basically encode any URL path (and optional arguments).
    106       id?: string;
    107 
    108     }