Быстрый старт

Данное руководство описывает минимальный набор действий для запуска верификации пользователей через OneKYC. По завершении четырёх шагов вы получите полностью функционирующую интеграцию: от создания сценария верификации до получения результатов.

Шаг 1. Получение доступа к платформе

Получите учётные данные для входа в административную панель OneKYC (предоставляются менеджером или при регистрации).
Авторизуйтесь в панели администратора.
Перейдите в раздел API-ключи и создайте API-ключ типа KYC:
- Среда: выберите test для разработки или live для продакшена.
- Scopes: выберите необходимые права доступа (для быстрого старта рекомендуется * — полный доступ).
Сохраните секрет ключа — он отображается однократно. Секрет необходим для формирования HMAC-подписи при вызове API.

Важно. Секрет ключа (с префиксом sk_) должен храниться исключительно на серверной стороне. Никогда не передавайте его на клиентскую сторону.

Шаг 2. Создание сценария верификации (Flow)

Перейдите в раздел Флоу административной панели:

Из шаблона (рекомендуется): откройте Галерею шаблонов и выберите готовый сценарий, например «Стандартный KYC» (документ + селфи + liveness) или «Базовый KYC» (только документ).
Вручную: нажмите «Создать флоу» и добавьте необходимые шаги в визуальном редакторе: загрузка документа, селфи, liveness-проверка, OTP, AML-скрининг, ручное ревью и др.

После настройки опубликуйте флоу. Скопируйте идентификатор флоу (flow_id) — он потребуется на следующем шаге.

Шаг 3. Создание ссылки верификации

Существует два способа создания ссылки верификации:

Способ A. Через Tenant API (рекомендуется для интеграции)

Отправьте запрос с серверной стороны, подписав его HMAC-подписью:

POST

/v1/kyc/verification-links

Authorization

ApiKeyAuth

headerAuthorization<token>

HMAC-SHA256 Credential=<key_id>, Signature=<hex_signature>. SignedHeaders=x-timestamp is optional. Requires X-Timestamp header.

Header Parameters

Request Body

Link options (flow_id required)

application/json

body

expires_in?integer

seconds

external_reference?string

external_user_id?string

flow_id?string

locale?string

metadata?

prefilled?

redirect_url?string

utm_campaign?string

utm_medium?string

utm_source?string

Response Body

Created or reused link

application/json

response

data?

success?boolean

Example Request

curl -X POST 'https://api.onekyc.io/tenant/v1/kyc/verification-links' \
  -H 'X-Timestamp: string' \
  -H 'Content-Type: application/json' \
  -d '{}'

Example Request

curl -X POST 'https://api.onekyc.io/tenant/v1/kyc/verification-links' \  -H 'X-Timestamp: string' \  -H 'Content-Type: application/json' \  -d '{}'

Example ResponseSchema

{
  "success": true,
  "data": {
    "created_at": "string",
    "delivery_eligible": true,
    "expires_at": "string",
    "external_reference": "string",
    "external_user_id": "string",
    "flow_id": "string",
    "id": "string",
    "link_url": "string",
    "locale": "string",
    "qr_code_url": "string",
    "redirect_url": "string",
    "reuse_reason": "external_reference",
    "reused": true,
    "session_id": "string",
    "session_resumable": true,
    "session_status": "string",
    "short_url": "string",
    "status": "string",
    "url": "string",
    "verification_link": "string",
    "verification_url": "string"
  }
}

{  "success": true,  "data": {    "created_at": "string",    "delivery_eligible": true,    "expires_at": "string",    "external_reference": "string",    "external_user_id": "string",    "flow_id": "string",    "id": "string",    "link_url": "string",    "locale": "string",    "qr_code_url": "string",    "redirect_url": "string",    "reuse_reason": "external_reference",    "reused": true,    "session_id": "string",    "session_resumable": true,    "session_status": "string",    "short_url": "string",    "status": "string",    "url": "string",    "verification_link": "string",    "verification_url": "string"  }}

Ключевые параметры запроса:

Параметр	Обязательный	Описание
`flow_id`	Да	Идентификатор опубликованного сценария верификации
`external_user_id`	Нет (рекомендуется)	Идентификатор пользователя в вашей системе. Позволяет связать результат верификации с вашим пользователем
`redirect_url`	Нет	URL для перенаправления после завершения верификации
`locale`	Нет	Язык интерфейса (`en`, `ru`)
`expires_in`	Нет	Время жизни ссылки в секундах (по умолчанию определяется настройками флоу)

Формирование HMAC-подписи: подробное описание алгоритма с примерами кода на JavaScript и Go приведено в разделе Аутентификация.

В ответе возвращается URL ссылки верификации. Передайте его пользователю по электронной почте, SMS, через мессенджер или в личном кабинете вашего приложения.

Способ B. Через административную панель (для тестирования)

Перейдите в раздел Ссылки верификации и нажмите «Создать ссылку»:

Выберите опубликованный флоу.
При необходимости укажите external_user_id, redirect_url и срок действия.
Скопируйте сгенерированную ссылку и откройте её в браузере для прохождения тестовой верификации.

Шаг 4. Регистрация вебхука для получения результатов

Для получения результатов верификации в реальном времени настройте вебхук:

Перейдите в раздел Вебхуки административной панели.
Нажмите «Создать эндпоинт».
Укажите URL вашего сервера, на который OneKYC будет отправлять уведомления.
Выберите типы событий — для начала рекомендуется подписаться на:
- verification.approved — верификация одобрена
- verification.declined — верификация отклонена
- verification.needs_review — верификация направлена на ручное ревью
Сохраните секрет вебхука (с префиксом whsec_) — он необходим для проверки подлинности входящих уведомлений на вашей стороне.

Проверка подписи: каждый вебхук содержит заголовок X-Onekyc-Signature с HMAC-SHA256 подписью. Подробнее о верификации подписи — в разделе Вебхуки.

Альтернативный способ — запрос через API:

GET

/v1/kyc/applicants

Authorization

ApiKeyAuth

headerAuthorization<token>

HMAC-SHA256 Credential=<key_id>, Signature=<hex_signature>. SignedHeaders=x-timestamp is optional. Requires X-Timestamp header.

Query Parameters

limit?integer

Limit (1-100, default 50)

offset?integer

Offset (default 0)

status?string

Filter by verification status

Value in"pending""verified""rejected""review"

Header Parameters

Response Body

Applicants list

application/json

response

data?array<>

pagination?

success?boolean

Example Request

curl -X GET 'https://api.onekyc.io/tenant/v1/kyc/applicants' \
  -H 'X-Timestamp: string'

Example Request

curl -X GET 'https://api.onekyc.io/tenant/v1/kyc/applicants' \  -H 'X-Timestamp: string'

Example ResponseSchema

{
  "pagination": {
    "has_more": true,
    "limit": 0,
    "next_cursor": "string",
    "offset": 0,
    "total": 0
  },
  "success": true,
  "data": [
    {
      "address": "string",
      "aml_decision": "string",
      "aml_risk_score": 0,
      "avatar_photo_url": "string",
      "avatar_url": "string",
      "client_liveness_score": 0,
      "created_at": "string",
      "current_review_decision": {
        "client_message": "string",
        "created_at": "string",
        "decision": "string",
        "id": "string",
        "reason_codes": [
          "string"
        ],
        "scope": "string",
        "session_id": "string",
        "step_id": "string"
      },
      "date_of_birth": "string",
      "details": {
        "address": {
          "city": "string",
          "country": "string",
          "full_text": "string",
          "localized": {
            "property1": {
              "property1": "string",
              "property2": "string"
            },
            "property2": {
              "property1": "string",
              "property2": "string"
            }
          },
          "postal_code": "string",
          "region": "string",
          "street": "string"
        },
        "barcode": {
          "fields": {
            "property1": "string",
            "property2": "string"
          },
          "raw": "string",
          "type": "string"
        },
        "document": {
          "booklet_number": "string",
          "class": "string",
          "issuing_authority": "string",
          "issuing_place": "string",
          "issuing_state_code": "string",
          "mrz_type": "string",
          "series": "string"
        },
        "localized": {
          "property1": {
            "property1": "string",
            "property2": "string"
          },
          "property2": {
            "property1": "string",
            "property2": "string"
          }
        },
        "mrz": {
          "document_code": "string",
          "fields": {
            "property1": "string",
            "property2": "string"
          },
          "issuing_state": "string",
          "raw": "string"
        },
        "personal": {
          "additional_fields": {
            "property1": "string",
            "property2": "string"
          },
          "nationality_name": "string",
          "personal_number": "string",
          "profession": "string",
          "tax_number": "string"
        },
        "provider": {
          "duration_ms": 0,
          "evidence_reuse": {
            "execution_id": "string",
            "reason": "string",
            "recovery_audit_id": "string",
            "source_attempt_number": 0,
            "source_execution_id": "string",
            "source_verification_id": "string"
          },
          "name": "string",
          "raw": {
            "property1": null,
            "property2": null
          },
          "raw_response_key": "string",
          "received_at": "string",
          "request_id": "string",
          "version": "string"
        }
      },
      "doc_liveness_score": 0,
      "document_back_key": "string",
      "document_back_url": "string",
      "document_front_key": "string",
      "document_front_url": "string",
      "document_number": "string",
      "document_photo_key": "string",
      "document_photo_url": "string",
      "document_type": "string",
      "email": "string",
      "enrichment": {
        "scope": "string",
        "summary": {
          "bankruptcy_confirmed": true,
          "call_statuses": {
            "property1": "string",
            "property2": "string"
          },
          "completed_at": "string",
          "hard_block_reason": "string",
          "match_count": 0,
          "merged_decision": "string",
          "merged_risk_score": 0,
          "observed_at": "string",
          "passport_invalid": true,
          "status": "string"
        }
      },
      "enrichment_errors": [
        "string"
      ],
      "expiry_date": "string",
      "expiry_status": "string",
      "external_id": "string",
      "face_match_score": 0,
      "first_name": "string",
      "full_name": "string",
      "full_name_latin": "string",
      "full_name_native": "string",
      "full_name_original": "string",
      "id": "string",
      "issuing_country": "string",
      "issuing_state_code": "string",
      "last_name": "string",
      "last_session_id": "string",
      "last_verified_at": "string",
      "latest_flow_name": "string",
      "liveness_mode": "string",
      "liveness_score": 0,
      "localized": {
        "property1": {
          "property1": "string",
          "property2": "string"
        },
        "property2": {
          "property1": "string",
          "property2": "string"
        }
      },
      "middle_name": "string",
      "name_source": {
        "property1": null,
        "property2": null
      },
      "nationality": "string",
      "phone": "string",
      "photo_url_expires_at": "string",
      "portrait_photo_key": "string",
      "portrait_photo_url": "string",
      "risk_score": 0,
      "risk_signals": {
        "property1": null,
        "property2": null
      },
      "selfie_photo_key": "string",
      "selfie_photo_url": "string",
      "session_summary": {
        "approved": 0,
        "in_progress": 0,
        "rejected": 0,
        "review": 0,
        "total": 0
      },
      "updated_at": "string",
      "verification_score": 0,
      "verification_status": "pending"
    }
  ]
}

{  "pagination": {    "has_more": true,    "limit": 0,    "next_cursor": "string",    "offset": 0,    "total": 0  },  "success": true,  "data": [    {      "address": "string",      "aml_decision": "string",      "aml_risk_score": 0,      "avatar_photo_url": "string",      "avatar_url": "string",      "client_liveness_score": 0,      "created_at": "string",      "current_review_decision": {        "client_message": "string",        "created_at": "string",        "decision": "string",        "id": "string",        "reason_codes": [          "string"        ],        "scope": "string",        "session_id": "string",        "step_id": "string"      },      "date_of_birth": "string",      "details": {        "address": {          "city": "string",          "country": "string",          "full_text": "string",          "localized": {            "property1": {              "property1": "string",              "property2": "string"            },            "property2": {              "property1": "string",              "property2": "string"            }          },          "postal_code": "string",          "region": "string",          "street": "string"        },        "barcode": {          "fields": {            "property1": "string",            "property2": "string"          },          "raw": "string",          "type": "string"        },        "document": {          "booklet_number": "string",          "class": "string",          "issuing_authority": "string",          "issuing_place": "string",          "issuing_state_code": "string",          "mrz_type": "string",          "series": "string"        },        "localized": {          "property1": {            "property1": "string",            "property2": "string"          },          "property2": {            "property1": "string",            "property2": "string"          }        },        "mrz": {          "document_code": "string",          "fields": {            "property1": "string",            "property2": "string"          },          "issuing_state": "string",          "raw": "string"        },        "personal": {          "additional_fields": {            "property1": "string",            "property2": "string"          },          "nationality_name": "string",          "personal_number": "string",          "profession": "string",          "tax_number": "string"        },        "provider": {          "duration_ms": 0,          "evidence_reuse": {            "execution_id": "string",            "reason": "string",            "recovery_audit_id": "string",            "source_attempt_number": 0,            "source_execution_id": "string",            "source_verification_id": "string"          },          "name": "string",          "raw": {            "property1": null,            "property2": null          },          "raw_response_key": "string",          "received_at": "string",          "request_id": "string",          "version": "string"        }      },      "doc_liveness_score": 0,      "document_back_key": "string",      "document_back_url": "string",      "document_front_key": "string",      "document_front_url": "string",      "document_number": "string",      "document_photo_key": "string",      "document_photo_url": "string",      "document_type": "string",      "email": "string",      "enrichment": {        "scope": "string",        "summary": {          "bankruptcy_confirmed": true,          "call_statuses": {            "property1": "string",            "property2": "string"          },          "completed_at": "string",          "hard_block_reason": "string",          "match_count": 0,          "merged_decision": "string",          "merged_risk_score": 0,          "observed_at": "string",          "passport_invalid": true,          "status": "string"        }      },      "enrichment_errors": [        "string"      ],      "expiry_date": "string",      "expiry_status": "string",      "external_id": "string",      "face_match_score": 0,      "first_name": "string",      "full_name": "string",      "full_name_latin": "string",      "full_name_native": "string",      "full_name_original": "string",      "id": "string",      "issuing_country": "string",      "issuing_state_code": "string",      "last_name": "string",      "last_session_id": "string",      "last_verified_at": "string",      "latest_flow_name": "string",      "liveness_mode": "string",      "liveness_score": 0,      "localized": {        "property1": {          "property1": "string",          "property2": "string"        },        "property2": {          "property1": "string",          "property2": "string"        }      },      "middle_name": "string",      "name_source": {        "property1": null,        "property2": null      },      "nationality": "string",      "phone": "string",      "photo_url_expires_at": "string",      "portrait_photo_key": "string",      "portrait_photo_url": "string",      "risk_score": 0,      "risk_signals": {        "property1": null,        "property2": null      },      "selfie_photo_key": "string",      "selfie_photo_url": "string",      "session_summary": {        "approved": 0,        "in_progress": 0,        "rejected": 0,        "review": 0,        "total": 0      },      "updated_at": "string",      "verification_score": 0,      "verification_status": "pending"    }  ]}

Готово!

Интеграция завершена. При переходе пользователя по ссылке верификации он проходит сценарий на странице OneKYC, а ваш сервер получает результат через вебхук.

Дальнейшие шаги

Аутентификация — детали HMAC-подписи, типы ключей, scopes
Вебхуки — полный перечень событий, формат payload, верификация подписи, политика повторных попыток
Аппликанты — получение данных верификации, документов, результатов AML
Ссылки верификации — жизненный цикл ссылок, пакетное создание, QR-коды
Флоу — настройка сценариев верификации через API
KYB API — верификация юридических лиц (бизнес-клиентов)
Ошибки и ограничения — коды ошибок, rate limits
Справочник API (OpenAPI) — интерактивная документация всех эндпоинтов

Быстрый старт

Шаг 1. Получение доступа к платформеCopy Anchor Link

Шаг 2. Создание сценария верификации (Flow)Copy Anchor Link

Шаг 3. Создание ссылки верификацииCopy Anchor Link

Способ A. Через Tenant API (рекомендуется для интеграции)Copy Anchor Link

AuthorizationCopy Anchor Link

Header ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

Способ B. Через административную панель (для тестирования)Copy Anchor Link

Шаг 4. Регистрация вебхука для получения результатовCopy Anchor Link

AuthorizationCopy Anchor Link

Query ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

Response BodyCopy Anchor Link

Готово!Copy Anchor Link

Дальнейшие шагиCopy Anchor Link

На этой странице

Шаг 1. Получение доступа к платформе

Шаг 2. Создание сценария верификации (Flow)

Шаг 3. Создание ссылки верификации

Способ A. Через Tenant API (рекомендуется для интеграции)

Authorization

Header Parameters

Request Body

Response Body

Способ B. Через административную панель (для тестирования)

Шаг 4. Регистрация вебхука для получения результатов

Authorization

Query Parameters

Header Parameters

Response Body

Готово!

Дальнейшие шаги