# Начало работы

Чтобы приступить к работе с IDnGO:

1. Войдите в Дешборд.
2. Настройте доступы для пользователей в вашей компании, пригласите свою команду и определите роли и разрешения.
3. Создайте уровень верификации.
4. Кастомизируйте верификацию под ваш сервис.
5. Пройдите аутентификацию.
6. Выберите подходящий способ интеграции:

WebSDK → iOS SDK → Android SDK → API-интеграция →

# Аутентификация

Чтобы начать работу с SDK и API от IDnGO, все клиенты должны пройти аутентификацию.

# App токен

В разделе «Панель разработчика» Дешборда нужно сгенерировать appToken и secretKey, далее на их основе генерируется accessToken.
Для каждого окружения (Тестовое или Основное) необходим свой App токен.

# Заголовки авторизации

Все API-запросы должны содержать следующие заголовки:

• X-App-Token — токен приложения, сгенерированный в панели управления;
• X-App-Access-Sig — подпись запроса в шестнадцатеричном формате, строчными буквами;
• X-App-Access-Ts — количество секунд с начала Unix-эпохи (в UTC).

# Подпись запроса

Значение X-App-Access-Sig генерируется алгоритмом HMAC-SHA256 с использованием секретного ключа secretKey (предоставляется при создании appToken) на основе строки, полученной путём объединения следующей информации:

1. Временная метка (значение заголовка X-App-Access-Ts);

2. Название HTTP-метода в верхнем регистре (например, GET или POST);
3. URI запроса без имени хоста, начиная со слэша и включая все параметры запроса, например: /resources/applicants/123?fields=info;
4. Тело запроса (если есть) в том виде, в каком оно будет отправлено.

Пример строки, из которой будет сгенерирована подпись:

1607551635POST/resources/accessTokens?userId=cfd20712-24a2-4c7d-9ab0-146f3c142335&levelName=basic-kyc-level&ttlInSecs=600

# POST Генерация токена доступа

При инициализации SDK необходимо использовать токен доступа accessToken. Для его получения нужно отправить запрос:

POST /resources/accessTokens?userId={userId}&levelName={levelName}

Токен доступа для верификации пользователя имеет ограниченный доступ к API, например, он действителен только для одного пользователя и не может быть использован для других.

Параметры запроса

Параметр запроса userId должен быть уникальным и осмысленным. Это может быть внешний идентификатор пользователя в вашей системе или адрес электронной почты. Не генерируйте эти идентификаторы случайным образом, если только вы не проводите тестирование.

Ответ

Пример

curl -X POST \
'https://api.cyberity.ru/resources/accessTokens?userId=JamesBond007&levelName=basic-kyc-level&ttlInSecs=600' \
  -H 'Accept: application/json'

{
  "token": "_act-b8ebfb63-5f24-4b89-9c08-5bbabeec986e",
  "userId": "JamesBond007"
}

# Вебхуки

Вебхуки от IDnGO — это инструмент, который позволяет автоматически получать уведомления о различных событиях и изменениях, связанных с процессом верификации ваших пользователей.

После завершения проверки пользователя мы отправим вам POST-запрос с полезной нагрузкой в формате JSON на URL, предоставленный нам при интеграции. Зачастую URL-адреса различаются для Тестового и Основного окружения.

Пожалуйста, протестируйте ваш вебхук, прежде чем отправлять его URL нам. Он не должен выдавать HTTP-ответ 500 или требовать какой-либо авторизации.

Вы можете отслеживать и анализировать каждое событие во вкладке «Журналы вебхуков».

На случай, если по какой-то причине вебхук не был получен, мы записываем все, что пытаемся отправить вам, и можем повторно отправить вебхук в любой момент. Если вебхук не удается отправить, мы делаем это повторно четыре раза: через 5 минут, 1 час, 5 и 18 часов, до тех пор пока запрос не будет успешным. Рекомендуем вам дожидаться вебхука не более суток, а затем отправить запрос на наш сервер для получения информации о статусе пользователя.

# Типы вебхуков

Настраивать типы, отслеживать статусы вебхуков и отправлять их вручную можно в разделе «Менеджер вебхуков».

Поля полезной нагрузки вебхука

# Причины отказа

Вебхук с результатом верификации содержит поле rejectLabels, в котором указаны один или более тегов, описывающих причину отказа. Теги rejectLabels нужны только для анализа результатов проверок и они лишь обобщенно описывают проблему, поэтому не стоит использовать их для генерации комментариев для пользователя.

Пример

# Пример полезной нагрузки вебхука applicantReviewed:

{
  "applicantId": "5cb744200a975a67ed1798a4", // applicant ID
  "inspectionId": "5cb744200a975a67ed1798a5", // applicant's inspection ID
  "correlationId": "req-fa94263f-0b23-42d7-9393-ab10b28ef42d",
  "externalUserId": "externalUserId",
  "type": "applicantReviewed",
  "reviewResult": {
    // A human-readable comment that can be shown to your end user
    // Please note that individual images may also contain additional document-specific comments.
    // In this case this field might be empty.
    // In order to get them, refer to the Getting applicant status (API)
    "moderationComment": "We could not verify your profile. Please contact support: support@cyberity.ru",
    // A human-readable comment that should not be shown to an end user, and is meant to be read by a client
    // This field will contain applicant's top-level comments,
    // plus, if the rejectType is not RETRY it may contain some private info, like that the user is a fraudster.
    // we envision that this field will be used for admin areas of our clients,
    // where a human can get all information
    "clientComment": " Suspected fraudulent account.",
    // final answer that should be highly trusted (only 'RED' and 'GREEN' are currently supported)
    "reviewAnswer": "RED",
    // a machine-readable constant that describes the problems in case of verification failure
    "rejectLabels": ["UNSATISFACTORY_PHOTOS", "GRAPHIC_EDITOR", "FORGERY"],
    "reviewRejectType": "FINAL"
  },
  // indicates that the verification process has been completed
  // NOTE: it does not mean that the applicant was approved,
  // it just means that an applicant was processed
  "reviewStatus": "completed",
  // time of webhook creation
  "createdAtMs": "2020-02-21 13:23:19.129"
}

{
  "applicantId": "5cb56e8e0a975a35f333cb83",
  "inspectionId": "5cb56e8e0a975a35f333cb84",
  "correlationId": "req-a260b669-4f14-4bb5-a4c5-ac0218acb9a4",
  "externalUserId": "externalUserId",
  "type": "applicantReviewed",
  "reviewResult": {
    "reviewAnswer": "GREEN"
  },
  "reviewStatus": "completed",
  "createdAtMs": "2020-02-21 13:23:19.091"
}

# Пример полезной нагрузки вебхука applicantCreated:

{
  "applicantId": "5c9e177b0a975a6eeccf5960",
  // inspection ID that contains a result
  "inspectionId": "5c9e177b0a975a6eeccf5961",
  // an ID to debug in case of unexpected errors (should be provided to IDnGO)
  "correlationId": "req-63f92830-4d68-4eee-98d5-875d53a12258",
  "levelName": "basic-kyc-level",
  "externalUserId": "12672",
  // type of webhook (see the corresponding section)
  "type": "applicantCreated",
  "sandboxMode": "false",
  "reviewStatus": "init",
  "createdAtMs": "2020-02-21 13:23:19.001",
  "clientId": "cyberityClient"
}

# Пример полезной нагрузки вебхука applicantPending:

{
  "applicantId": "5c7791f80a975a1df426b9e9",
  "inspectionId": "5c7791f80a975a1df426b9ea",
  "applicantType" : "individual",
  "correlationId": "req-4af54c06-6a50-4cb9-a7dc-b94b2f5b07eb",
  "levelName": "liveness-level",
  "externalUserId": "12672",
  "type": "applicantPending",
  "sandboxMode": "false",
  "reviewStatus": "pending",
  "createdAtMs": "2020-02-21 13:23:19.001",
  "clientId": "cyberityClient"
}

# Пример полезной нагрузки вебхука applicantOnHold:

{
  "inspectionId": "5d10ca4e0a975a1c4cc30bbb",
  "applicantType" : "individual",
  "correlationId": "req-a98abc30-a5d9-4e1d-bab4-2f1af64bd5a5",
  "levelName": "poa-level",
  "externalUserId": "12672",
  "reviewStatus": "onHold",
  "applicantId": "5d10ca4e0a975a1c4cc30bba",
  "type": "applicantOnHold",
  "sandboxMode": "true",
  "createdAtMs": "2020-02-21 13:23:19.001",
  "clientId": "cyberityClient"
}

# Пример полезной нагрузки вебхука applicantPersonalInfoChanged:

{
  "applicantId" : "5ede51230a975a19a19ba5c1",
  "inspectionId" : "5ede51230a975a19a19ba5c2",
  "applicantType" : "individual",
  "correlationId" : "req-60103dee-79f1-43f4-bdcc-eb2554556afa",
  "levelName": "id+liveness",
  "externalUserId" : "12672",
  "type" : "applicantPersonalInfoChanged",
  "sandboxMode": "false",
  "reviewResult" : {
    "reviewAnswer" : "GREEN"
  },
  "reviewStatus" : "completed",
  "createdAtMs" : "2020-06-08 19:39:29.001",
  "clientId": "cyberityClient"
}

# Пример полезной нагрузки вебхука applicantPrechecked:

{
  "applicantId": "5d1f2914c2d75a1c14130bd2",
  "inspectionId": "5d1f2914c2d75a1c14130bd3",
  "applicantType" : "individual",
  "correlationId": "req-e9d77142-59e6-4713-9b07-9b342cc51dda",
  "levelName": "kyc",
  "externalUserId": "12672",
  "type": "applicantPrechecked",
  "sandboxMode": "false",
  "reviewStatus": "queued",
  "createdAtMs": "2020-02-21 13:23:19.001",
  "clientId": "cyberityClient"
}

# Пример полезной нагрузки вебхука applicantDeleted:

{
  "applicantId": "5f194e74040c3f316bda271c",
  "inspectionId": "5f194e74040c3f316bda271d",
  "applicantType": "individual",
  "correlationId": "req-d34c974c-5935-41b8-a0a9-cedd2407eada",
  "levelName": "phone-level",
  "externalUserId": "12672",
  "type": "applicantDeleted",
  "sandboxMode": "false",
  "reviewStatus": "init",
  "createdAtMs": "2020-07-23 11:18:33.001",
  "clientId": "cyberityClient"
}

# Пример полезной нагрузки вебхука applicantLevelChanged:

{
  "applicantId": "5f194e74040c3f316bda271c",
  "inspectionId": "5f194e74040c3f316bda271d",
  "applicantType": "individual",
  "correlationId": "req-d34c974c-5935-41b8-a0a9-cedd2407eadd",
  "levelName": "basic-kyc-level",
  "externalUserId": "12672",
  "type": "applicantLevelChanged",
  "sandboxMode": "false",
  "reviewStatus": "init",
  "createdAtMs": "2020-07-23 11:19:33.002",
  "clientId": "cyberityClient"
}

# Пример полезной нагрузки вебхука applicantReset:

{
  "applicantId": "5f194e74040c3f316bda271c",
  "inspectionId": "5f194e74040c3f316bda271d",
  "applicantType": "individual",
  "correlationId": "req-57fed49a-07b8-4413-bdaa-a1be903769e9",
  "levelName": "basic-kyc-level",
  "externalUserId": "12672",
  "type": "applicantReset",
  "sandboxMode": "false",
  "reviewResult": {
    "reviewAnswer": "GREEN"
  },
  "reviewStatus": "init",
  "createdAtMs": "2021-03-01 11:34:51.001",
  "clientId": "cyberityClient"
}

# Проверка отправителя вебхука

Лучше не полагаться на наши IP-адреса при составлении белого списка отправителей вебхуков, поскольку они могут время от времени меняться.

Чтобы убедиться, что вебхук отправлен именно нами, можно воспользоваться подписью с помощью алгоритма HMAC. Если вы хотите воспользоваться этой функцией, задайте значение секретного ключа для каждого вебхука и выберите алгоритм HMAC в «Панели разработчика» Дешборда.

При использовании подписи мы также отправляем дополнительный заголовок X-Payload-Digest-Alg, в котором указывается один из следующих алгоритмов:

• HMAC_SHA1_HEX — устарел
• HMAC_SHA256_HEX — используется по умолчанию при создании нового вебхука
• HMAC_SHA512_HEX

Инструкция проверки отправителя вебхука:

1. Получите значение заголовка вебхука x-payload-digest и полезную нагрузку как она есть, без каких-либо изменений или преобразования в JSON.
2. Получите тело HTTP-вебхука в байтах.
3. Вычислите контрольное значение (digest) с использованием исходной полезной нагрузки в байтах и алгоритма HMAC, указанного в заголовке x-payload-digest-alg.
4. Сравните значение заголовка x-payload-digest с вычисленным вами контрольным значением.

Проверка отправителя вебхука: POST /resources/inspectionCallbacks/testDigest?secretKey={secretKey}

# Пример запроса к вашему эндпоинту:

curl -X POST \
  'https://callbackurl.com/kyc' \
  -H 'Content-Type: application/json' \
  -d '{
    "applicantId": "5cb56e8e0a975a35f333cb83",
    "inspectionId": "5cb56e8e0a975a35f333cb84",
    "correlationId": "req-ec508a2a-fa33-4dd2-b93d-fcade2967e03",
    "externalUserId": "12672",
    "type": "applicantReviewed",
    "reviewResult": {
        "reviewAnswer": "GREEN"
    },
    "reviewStatus": "completed",
    "createdAtMs": "2020-02-21 13:23:19.111",
    "clientId": "CyberityClient"
}'

# Пример вычисления контрольного значения digest:

export function checkDigest(req): boolean {
 const algo = {
  'HMAC_SHA1_HEX': 'sha1',
  'HMAC_SHA256_HEX': 'sha256',
  'HMAC_SHA512_HEX': 'sha512',
 }[req.headers['X-Payload-Digest-Alg']]

 if (!algo) {
  throw new Error('Unsupported algorithm')
 }

 const calculatedDigest = crypto
  .createHmac(algo, CYBERIRTY_PRIVATE_KEY)
  .update(req.rawBody)
  .digest('hex')

 return calculatedDigest === req.headers['x-payload-digest']
}

private async Task<bool> CheckDigest(HttpRequest request)
{
    using (var reader = new StreamReader(request.Body))
    {
        var body = await reader.ReadToEndAsync();

        byte[] byteArray = Encoding.UTF8.GetBytes(body);
        MemoryStream stream = new MemoryStream(byteArray);

        string algo = Request.Headers["x-payload-digest-alg"];

        var calculateDigest = new { };

        switch (algo)
        {
            case "HMAC_SHA1_HEX":
                HMACSHA1 hmacsha1 = new HMACSHA1(Encoding.UTF8.GetBytes(_verificationAccessor.CyberityPrivateKey));
                calculateDigest = hmacsha1.ComputeHash(stream).Aggregate("", (s, e) => s + String.Format("{0:x2}", e), s => s);
                break;
            case "HMAC_SHA256_HEX":
                HMACSHA256 hmacsha256 = new HMACSHA256(Encoding.UTF8.GetBytes(_verificationAccessor.CyberityPrivateKey));
                calculateDigest = hmacsha1.ComputeHash(stream).Aggregate("", (s, e) => s + String.Format("{0:x2}", e), s => s);
                break;
            case "HMAC_SHA512_HEX":
                HMACSHA512 hmacsha512 = new HMACSHA512(Encoding.UTF8.GetBytes(_verificationAccessor.CyberityPrivateKey));
                calculateDigest = hmacsha512.ComputeHash(stream).Aggregate("", (s, e) => s + String.Format("{0:x2}", e), s => s);
                break;
            default:
                HMACSHA256 hmacsha256 = new HMACSHA256(Encoding.UTF8.GetBytes(_verificationAccessor.CyberityPrivateKey));
                calculateDigest = hmacsha1.ComputeHash(stream).Aggregate("", (s, e) => s + String.Format("{0:x2}", e), s => s);
                break;
        }

        return calculateDigest == Request.Headers["x-payload-digest"];
    };
}

public function validateWebHook(HttpRequest $request, string $content): void
{
    $algo = match($request->headers->get('X-Payload-Digest-Alg')) {
      'HMAC_SHA1_HEX' => 'sha1',
      'HMAC_SHA256_HEX' => 'sha256',
      'HMAC_SHA512_HEX' => 'sha512',
      default => throw new \RuntimeException('Unsupported algorithm'),
    };

    $res = $request->headers->get('X-Signature') === hash_hmac(
        $algo,
        $content,
        'your_secret_key'
    );

    if (!$res) {
        $this->logger->error('Webhook Cyberity sign ' . $content);
        throw new LogicProfileException('Webhook Cyberity sign ' . $content);
    }
}