KYC Flow
########


Get client's KYC level
**********************

    `GET /v1/clients/kyc-level-info/ <https://api.app.stasis.net/docs#/KYC/get_v1_clients_kyc_level_info>`_

    .. code-block:: python

        query = {
            "legal_entity_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "client_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        }

    The response will help you understand whether a KYC application can be created
    (``allowed_to_create_kyc_application``) and what KYC levels a client can receive
    (``available_levels_for_upgrade``), as well as the UUID of the last KYC application
    (``last_kyc_application_uuid``).

Create KYC application
**********************

    `POST /v1/clients/kyc-level-info/ <https://api.app.stasis.net/docs#/KYC/get_v1_kyc>`_

    .. code-block:: python

        query = {
            "legal_entity_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "client_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        }

    .. code-block:: python

        data = {
            "kyc_level_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        }

    In response, you will receive an KYC questionnaire that the client will have to fill out.

Update KYC application
**********************

    `PATCH /v1/kyc/{*kyc_application_uuid*}/ <https://api.app.stasis.net/docs#/KYC/patch_v1_kyc_application_uuid>`_

    .. code-block:: python

        query = {
            "legal_entity_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "client_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        }

    .. code-block:: python

        data = {
            "attribute_changes": [
                "key": "string",
                "value": "string"
            ]
        }

    The KYC questionnaire can be filled out in parts or all at once.

    **Using the KYC questionnaire, client attributes are filled in.**
    **Client attributes have a specific type. Let's talk about some of them:**

Reference data
--------------

    Attribute with selection from a list.

    Get attribute definitions:

    `GET /v1/attributes/{*attribute_key*}/definitions/ <https://api.app.stasis.net/docs#/Attributes/get_v1_attributes_attribute_key_definitions>`_

Legal document
--------------

    Legal document that the client must read.

    `GET /v1/legal_documents/ <https://api.app.stasis.net/docs#/Legal%20Documents/get_v1_legal_documents>`_

    .. code-block:: python

        query = {
            "legal_entity_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "client_type": "individual",
            "key": "string"
        }

    The attribute value must contain the legal document UUID.

Document
--------

    Document that the client must upload.

    First upload the file(s):

    `POST /v1/documents/files/ <https://api.app.stasis.net/docs#/Documents/post_v1_documents_files>`_

    .. code-block:: python

        query = {
            "legal_entity_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "client_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        }

    .. code-block:: python

        files = {}

    Then create a document based on the previously uploaded file(s):

    `POST /v1/documents/ <https://api.app.stasis.net/docs#/Documents/post_v1_documents>`_

    .. code-block:: python

        query = {
            "legal_entity_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "client_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        }

    .. code-block:: python

        data = {
            "attribute_key": "string",
            "files": []
        }

    Put the response in the attribute value.

    **Attribute Keys for documents:**

        * ``passport``
        * ``id_card_front_side``
        * ``id_card_back_side``
        * ``driver_license_front_side``
        * ``driver_license_back_side``
        * ``residence_permit_license_front_side``
        * ``residence_permit_license_back_side``
        * ``proof_of_address``
        * ``proof_of_funds``

        In case the document is single-sided, please send its "back side" also,
        but use any picture for this. For instance the one you used as "front side".

SumSub liveness check
---------------------

    Some KYC levels need SumSub liveness Check. There are 2 ways of passing this:
        #. Getting an URL leading your customers to https://sumsub.com/ which will guide them through liveness check process.

            attribute_key: ``sumsub_liveness_check_url``
        #. Getting a token allowing you to embed SumSub widget on your web page by following this instruction https://docs.sumsub.com/docs/get-started-with-web-sdk#standalone-example-of-websdk-initialization .

            attribute_key: ``sumsub_liveness_check_token``

    In the both cases your customers will be asked to turn on their camera in order to make some photos.

    `GET /v1/kyc/{*kyc_application_uuid*}/ <https://api.app.stasis.net/docs#/KYC/get_v1_kyc_application_uuid>`_

    .. code-block:: python

        query = {
            "empty_volatile_fields": false,
            "sumsub_liveness_check_token.ttl_min": 600,
            "sumsub_liveness_check_token.ttl_max": 3600,
            "sumsub_liveness_check_token.ttl_renew": false
        }

        response = {
            kyc_steps[] -> "title": "Liveness check" -> questions[] -> "title": "SumSub liveness check token" -> attribute -> {
                "value": "accessToken",
                "additional_info" {
                    "email": "email",
                    "phone": "phone"
                },
                ...
            }
        }

    `GET /v1/kyc/{*kyc_application_uuid*}/attributes/{attribute_key}/ <https://api.app.stasis.net/docs#/KYC/get_v1_kyc_application_uuid_attributes_attribute_key>`_

    .. code-block:: python

        path = {
            "attribute_key": "sumsub_liveness_check_token"
        }

        query = {
            "ttl_min": 600,
            "ttl_max": 3600,
            "ttl_renew": false,
            ...
        }

        response = {
            "value": "accessToken",
            "additional_info" {
                "email": "email",
                "phone": "phone"
            },
            ...
        }

    **We recommend refreshing token with 'ttl_renew=true' whenever SumSub stops accepting it.**

    **Note:** Each Liveness access token is bound to a particular customer and cannot be used by
    other customers(even if the corresponding email/phone are provided).

Client signature
----------------

    Some attributes require the client's signature. Such attributes have a ``sign_providers`` field,
    by which you can select the desired signature type.

    Send verification code:

    `POST /v1/verification-codes/ <https://api.app.stasis.net/docs#/Documents/post_v1_verification_codes>`_

    .. code-block:: python

        query = {
            "legal_entity_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "client_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            ...
        }

    .. code-block:: python

        data = {
            "legal_entity_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "object_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "provider_type": "sms",
            "destination": "string"
        }

    In ``object_uuid`` you need to put ``kyc_application_uuid``.
    The destination field must be filled in when a client first enters or changes a phone number.

    Therefore, you may need to add the following query parameters to the KYC application update request:

    .. code-block:: python

        query = {
            ...,
            "email_sign_code": "string",
            "sms_sign_code": "string"
        }

    **Note:** If you are sending multiple attributes with the same signature type in a single
    KYC application update request, then one signature code is sufficient.
    The signature code on the sandbox is **111111**.

Send KYC application to review
******************************

    `POST /v1/kyc/{*kyc_application_uuid*}/send-to-review/ <https://api.app.stasis.net/docs#/KYC/post_v1_kyc_application_uuid_send_to_review>`_

    .. code-block:: python

        query = {
            "legal_entity_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "client_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        }

    Sending a KYC application to review may also require a client signature.

Get KYC application review result
*********************************

    If you receive a *pending* status, KYC application will need to be corrected using the instructions for
    :ref:`Update KYC application` step and sent again to review.
    The rejected status is final and a new KYC application will need to be created.

    `GET /v1/kyc/{*kyc_application_uuid*}/ <https://api.app.stasis.net/docs#/KYC/get_v1_kyc_application_uuid>`_

    For some documents it is possible to retrieve SumSub document diagnostics as:

    .. code-block:: python

        response = {
            kyc_steps[] -> "title": "Liveness check" -> questions[] -> "title": "SumSub liveness check token" -> attribute -> value -> {
                "verification": {
                    "sumsub": {
                        "verificator": "sumsub",
                        "status": "ignored",
                        "client_note": "There is no available data to recognize from image"
                    }
                }
            }
        }

    **Note:** The developer's application on the sandbox provides a function for changing the status
    of the KYC application.

    * `POST /v1/kyc/{*kyc_application_uuid*}/approve/ <https://api.sandbox.stasis.net/docs#/KYC/post_v1_kyc_application_uuid_approve>`_
    * `POST /v1/kyc/{*kyc_application_uuid*}/reject/ <https://api.sandbox.stasis.net/docs#/KYC/post_v1_kyc_application_uuid_reject>`_
    * `POST /v1/kyc/{*kyc_application_uuid*}/send-to-clarify/ <https://api.sandbox.stasis.net/docs#/KYC/post_v1_kyc_application_uuid_send_to_clarify>`_