taler-docs

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

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

      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 the serial ID of the measure. 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 
     45 
     46   **Details:**
     47 
     48   .. ts:def:: KycProcessClientInformation
     49 
     50     interface KycProcessClientInformation {
     51 
     52       // Array of requirements.
     53       requirements: KycRequirementInformation[];
     54 
     55       // True if the client is expected to eventually satisfy all requirements.
     56       // Default (if missing) is false.
     57       is_and_combinator?: boolean
     58 
     59       // List of available voluntary checks the client could undertake.
     60       // @since protocol **vATTEST**.
     61       voluntary_measures?: KycRequirementInformation[];
     62     }
     63 
     64   .. ts:def:: KycRequirementInformation
     65 
     66     interface KycRequirementInformation {
     67 
     68       // Which form should be used? Common values include "INFO"
     69       // (to just show the descriptions but allow no action),
     70       // "LINK" (to enable the user to obtain a link via
     71       // ``/kyc-start/``) or any build-in form name supported
     72       // by the SPA.
     73       form: string;
     74 
     75       // Object with arbitrary additional context, completely depends on
     76       // the specific form.
     77       context?: Object;
     78 
     79       // English description of the requirement.
     80       description: string;
     81 
     82       // Map from IETF BCP 47 language tags to localized
     83       // description texts.
     84       description_i18n ?: { [lang_tag: string]: string };
     85 
     86       // ID of the requirement, useful to construct the
     87       // ``/kyc-upload/$ID`` or ``/kyc-start/$ID`` endpoint URLs.
     88       // Present if and only if "form" is not "INFO".  The
     89       // ``$ID`` value may itself contain ``/`` or ``?`` and
     90       // basically encode any URL path (and optional arguments).
     91       id?: string;
     92 
     93     }