Ссылки верификации

Ссылки верификации представляют собой одноразовые или ограниченные по времени URL-адреса, по которым пользователь инициирует процедуру верификации. Ссылки создаются через Tenant API или в административной панели и передаются пользователю (по электронной почте, SMS, QR-коду или в личном кабинете). При переходе по ссылке автоматически создаётся или привязывается сессия верификации, и пользователь перенаправляется на страницу верификации OneKYC.

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

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"  }}

Внешний ID и незавершённая ручная проверка

external_user_id идентифицирует заявителя внутри тенанта и не является ID сессии. У одного заявителя может быть несколько исторических сессий. Продолжение проверки определяется сочетанием тенанта, окружения, внешнего ID, воронки и типа KYC/KYB.

Если по этому сочетанию остаётся незавершённая ручная проверка, создание новой ссылки возвращает HTTP 409, error.code = "session_review_pending" и error.existing_session_id. Завершите текущее ревью или запросите пересдачу в нём. Истечение срока ссылки не завершает ревью. Дублирование ссылки и активация заранее созданной новой ссылки не обходят эту проверку.

Для сессии в процессе обычное создание ссылки продолжает использовать текущую сессию. После итогового одобрения или отклонения можно начать независимую проверку. external_reference повторно использует подходящую активную ссылку только если external_user_id не указан или совпадает с ID ссылки; для другого внешнего ID создаётся отдельная ссылка. Параметр не задаёт пожизненную уникальность сессии. При пакетном создании конфликт указывается для соответствующего элемента.

Сопоставляйте webhook-события по session_id вместе с external_id: позднее решение по исторической сессии относится к ней и не должно автоматически заменять результат другой сессии с тем же внешним ID.

Легаси-совместимость

Канонический KYC-путь — /tenant/v1/kyc/verification-links. Для существующих интеграций тенантов OneKYC также намеренно поддерживает /tenant/v1/verification-links и /tenant/v1/verificationLinks как KYC-алиасы. Тела запросов create и batch-create для verification links также принимают легаси-алиасы полей с разным регистром или разделителями, например flowId, FlowID, externalUserId, redirectUrl и prefilledData.

Эти алиасы нельзя считать мертвым кодом. Это поддерживаемый compatibility contract, который можно удалять только после отдельного versioned deprecation и migration window для Tenant API.

Пакетное создание ссылок

Позволяет создать несколько ссылок верификации в рамках одного запроса.

POST

/v1/kyc/verification-links/batch

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

Batch create request

application/json

body

defaults?

items?array<>

Response Body

Created links

application/json

response

data?

success?boolean

Example Request

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

Example Request

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

Example ResponseSchema

{
  "success": true,
  "data": {
    "failed": [
      {
        "error": "string",
        "error_code": "string",
        "existing_session_id": "string",
        "index": 0,
        "link": {
          "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"
        }
      }
    ],
    "successful": [
      {
        "error": "string",
        "error_code": "string",
        "existing_session_id": "string",
        "index": 0,
        "link": {
          "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"
        }
      }
    ],
    "summary": {
      "failed": 0,
      "successful": 0,
      "total": 0
    }
  }
}

{  "success": true,  "data": {    "failed": [      {        "error": "string",        "error_code": "string",        "existing_session_id": "string",        "index": 0,        "link": {          "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"        }      }    ],    "successful": [      {        "error": "string",        "error_code": "string",        "existing_session_id": "string",        "index": 0,        "link": {          "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"        }      }    ],    "summary": {      "failed": 0,      "successful": 0,      "total": 0    }  }}

Получение списка ссылок

GET

/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.

Query Parameters

page?integer

Page (1-based)

page_size?integer

Page size (1-100)

status?string

Filter by status (active, consumed, revoked)

external_user_id?string

Filter by external user ID

external_reference?string

Filter by external reference

flow_id?string

Filter by flow UUID

sort_by?string

Sort field (default created_at)

sort_order?string

Sort order: asc, desc (default desc)

Header Parameters

Response Body

Verification links

*/*

response

data?

success?boolean

Example Request

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

Example Request

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

Example ResponseSchema

{
  "success": true,
  "data": {
    "items": [
      {
        "activated_at": "string",
        "consumed_at": "string",
        "created_at": "string",
        "created_by": "string",
        "expires_at": "string",
        "external_reference": "string",
        "external_user_id": "string",
        "flow_id": "string",
        "flow_session_id": "string",
        "id": "string",
        "locale": "string",
        "metadata": {
          "property1": null,
          "property2": null
        },
        "prefilled_data": {
          "property1": null,
          "property2": null
        },
        "redirect_url": "string",
        "revoked_at": "string",
        "revoked_reason": "string",
        "short_code": "string",
        "status": "string",
        "token": "string",
        "updated_at": "string",
        "utm_campaign": "string",
        "utm_medium": "string",
        "utm_source": "string"
      }
    ],
    "pagination": {
      "page": 0,
      "page_size": 0,
      "total": 0,
      "total_pages": 0
    }
  }
}

{  "success": true,  "data": {    "items": [      {        "activated_at": "string",        "consumed_at": "string",        "created_at": "string",        "created_by": "string",        "expires_at": "string",        "external_reference": "string",        "external_user_id": "string",        "flow_id": "string",        "flow_session_id": "string",        "id": "string",        "locale": "string",        "metadata": {          "property1": null,          "property2": null        },        "prefilled_data": {          "property1": null,          "property2": null        },        "redirect_url": "string",        "revoked_at": "string",        "revoked_reason": "string",        "short_code": "string",        "status": "string",        "token": "string",        "updated_at": "string",        "utm_campaign": "string",        "utm_medium": "string",        "utm_source": "string"      }    ],    "pagination": {      "page": 0,      "page_size": 0,      "total": 0,      "total_pages": 0    }  }}

Получение ссылки по идентификатору

GET

/v1/kyc/verification-links/{id}

Authorization

ApiKeyAuth

headerAuthorization<token>

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

Path Parameters

id*string

Link UUID

Header Parameters

Response Body

Verification link details

*/*

response

data?

success?boolean

Example Request

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

Example Request

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

Example ResponseSchema

{
  "success": true,
  "data": {
    "activated_at": "string",
    "consumed_at": "string",
    "created_at": "string",
    "created_by": "string",
    "expires_at": "string",
    "external_reference": "string",
    "external_user_id": "string",
    "flow_id": "string",
    "flow_session_id": "string",
    "id": "string",
    "locale": "string",
    "metadata": {
      "property1": null,
      "property2": null
    },
    "prefilled_data": {
      "property1": null,
      "property2": null
    },
    "redirect_url": "string",
    "revoked_at": "string",
    "revoked_reason": "string",
    "short_code": "string",
    "status": "string",
    "token": "string",
    "updated_at": "string",
    "utm_campaign": "string",
    "utm_medium": "string",
    "utm_source": "string"
  }
}

{  "success": true,  "data": {    "activated_at": "string",    "consumed_at": "string",    "created_at": "string",    "created_by": "string",    "expires_at": "string",    "external_reference": "string",    "external_user_id": "string",    "flow_id": "string",    "flow_session_id": "string",    "id": "string",    "locale": "string",    "metadata": {      "property1": null,      "property2": null    },    "prefilled_data": {      "property1": null,      "property2": null    },    "redirect_url": "string",    "revoked_at": "string",    "revoked_reason": "string",    "short_code": "string",    "status": "string",    "token": "string",    "updated_at": "string",    "utm_campaign": "string",    "utm_medium": "string",    "utm_source": "string"  }}

Отзыв ссылки

Отозванная ссылка становится недействительной и не может быть использована для инициации верификации.

POST

/v1/kyc/verification-links/{id}/revoke

Authorization

ApiKeyAuth

headerAuthorization<token>

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

Path Parameters

id*string

Link UUID

Header Parameters

Request Body

Optional revoke reason

application/json

body

reason?string

Response Body

Revoked link info

application/json

response

data?

success?boolean

Example Request

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

Example Request

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

Example ResponseSchema

{
  "success": true,
  "data": {
    "id": "string",
    "revoked_at": "string",
    "status": "string"
  }
}

{  "success": true,  "data": {    "id": "string",    "revoked_at": "string",    "status": "string"  }}

Получение QR-кода

Возвращает QR-код для ссылки верификации. Используется для реализации cross-device flow: пользователь сканирует QR-код на мобильном устройстве и продолжает верификацию.

GET

/v1/kyc/verification-links/{id}/qr

Authorization

ApiKeyAuth

headerAuthorization<token>

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

Path Parameters

id*string

Link UUID

Query Parameters

size?integer

QR size in pixels (1-1024, default 256)

Header Parameters

Response Body

PNG image

response?unknownimage/png

Example Request

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

Example Request

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

Example ResponseSchema

null

null

Жизненный цикл ссылки

[Created] → [Activated] → [Consumed]
    ↓            ↓            ↓
[Expired]   [Expired]   [Completed]
    ↓            ↓
[Revoked]   [Revoked]

Статусы ссылки:

Статус	Описание
`active`	Ссылка создана; пользователь ещё не переходил по ней
`activated`	Пользователь перешёл по ссылке; создана сессия, верификация в процессе
`consumed`	Верификация завершена (одобрена, отклонена или направлена на ревью)
`expired`	Истёк срок действия ссылки (`ttl_seconds`); ссылка более недоступна
`revoked`	Ссылка отозвана вручную через API или административную панель

Примечание. После создания ссылки передайте её пользователю (по электронной почте, SMS, QR-коду). При переходе по ссылке автоматически создаётся сессия верификации. Для реализации cross-device flow используйте QR-код (GET /v1/kyc/verification-links/{id}/qr).

Редирект после завершения верификации

При создании ссылки допускается указание параметра redirect_url — URL-адреса, на который пользователь будет перенаправлен после завершения процедуры верификации (например, личный кабинет или форма заявки).

Порядок работы

При создании ссылки в теле запроса передаётся параметр redirect_url (POST /v1/kyc/verification-links или batch).
При активации ссылки redirect_url сохраняется в сессию и возвращается в ответе активации (поле redirect_url).
На экране завершения (после одобрения, отклонения или направления на ревью) пользователю отображается:
- кнопка возврата — пользователь нажимает и переходит по redirect_url;
- либо автоматический редирект через заданный интервал времени.

Настройка поведения

Поведение редиректа настраивается в параметрах флоу в административной панели:

Redirect behavior on completion — режим перенаправления: «Show button» (отображение кнопки) или «Auto redirect» (автоматическое перенаправление).
Redirect delay (seconds) — задержка в секундах перед автоматическим перенаправлением (применяется в режиме «Auto redirect»).

Значения по умолчанию: отображение кнопки; при автоматическом режиме задержка составляет 3 секунды. Подробнее — в разделе Флоу (админка).

Ссылки верификации

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

AuthorizationCopy Anchor Link

Header ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

Внешний ID и незавершённая ручная проверкаCopy Anchor Link

Легаси-совместимостьCopy Anchor Link

Пакетное создание ссылокCopy Anchor Link

AuthorizationCopy Anchor Link

Header ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

Получение списка ссылокCopy Anchor Link

AuthorizationCopy Anchor Link

Query ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

Response BodyCopy Anchor Link

Получение ссылки по идентификаторуCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

Response BodyCopy Anchor Link

Отзыв ссылкиCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

Получение QR-кодаCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Query ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

Response BodyCopy Anchor Link

Жизненный цикл ссылкиCopy Anchor Link

Редирект после завершения верификацииCopy Anchor Link

Порядок работыCopy Anchor Link

Настройка поведенияCopy Anchor Link

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

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

Authorization

Header Parameters

Request Body

Response Body

Внешний ID и незавершённая ручная проверка

Легаси-совместимость

Пакетное создание ссылок

Authorization

Header Parameters

Request Body

Response Body

Получение списка ссылок

Authorization

Query Parameters

Header Parameters

Response Body

Получение ссылки по идентификатору

Authorization

Path Parameters

Header Parameters

Response Body

Отзыв ссылки

Authorization

Path Parameters

Header Parameters

Request Body

Response Body

Получение QR-кода

Authorization

Path Parameters

Query Parameters

Header Parameters

Response Body

Жизненный цикл ссылки

Редирект после завершения верификации

Порядок работы

Настройка поведения