Параметры ссылки сессии¶

Каждый эндпоинт, который выдаёт ссылку на сессию — POST /v1/applicants/{externalUserId}/verifications, POST /v1/applicants/{externalUserId}/verification-sessions, POST /v1/applicants/{externalUserId}/ubos/{uboIndex}/spawn-kyc, POST /v1/applicants/{externalUserId}/ubos/{uboIndex}/regenerate-link — принимает один и тот же набор настроек отображения. Передавайте их в query-параметрах (на эндпоинтах, где данные идут через URL) или в теле JSON (на эндпоинтах spawn-kyc и regenerate-link).

Hosted SDK читает их из URL ссылки во время запуска — пользователь попадает в уже преднастроенный интерфейс.

Доступные параметры¶

Параметр	Тип	Эффект	По умолчанию
`lang`	ISO-639 код (`en`, `ru`, …)	Закрепляет язык SDK. Пусто → язык браузера, затем английский.	не задано
`theme`	`light` \| `dark` \| `system`	Закрепляет светлую/тёмную тему; `system` следует за настройкой ОС.	`system`
`returnUrl`	http(s) URL	Куда перенаправить пользователя в обоих исходах. Должен быть валидным абсолютным URL — некорректные значения молча игнорируются, и пользователь остаётся на финальном экране SDK.	не задано
`successUrl`	http(s) URL	Перенаправление только при успешном завершении. Имеет приоритет над `returnUrl` для успеха.	по умолчанию `returnUrl`
`errorUrl`	http(s) URL	Перенаправление только при финальной ошибке / отклонении. Имеет приоритет над `returnUrl` для ошибки.	по умолчанию `returnUrl`

successUrl / errorUrl нужны, когда последующие UX разные: успех возвращает пользователя в ваш онбординг-визард, ошибка ведёт на страницу «связаться с поддержкой». Обычный returnUrl достаточен, если оба исхода ведут на один и тот же экран.

Примеры¶

Через URL (verification-sessions)¶

curl -X POST 'https://api.compliance.example/v1/applicants/user-12345/verification-sessions?verificationLevelName=KYC_01&lang=ru&theme=dark&returnUrl=https://acme.com/done' \
  -H 'X-Api-Key: pk_live_...' \
  -H 'X-Api-Secret: ...' \
  -H 'X-Environment: production'

Вариант с раздельными редиректами — успех ведёт обратно в визард, ошибка — в поддержку:

curl -X POST 'https://api.compliance.example/v1/applicants/user-12345/verification-sessions?verificationLevelName=KYC_01&successUrl=https://acme.com/onboarding/step-3&errorUrl=https://acme.com/support/kyc-help' \
  -H 'X-Api-Key: pk_live_...' \
  -H 'X-Api-Secret: ...' \
  -H 'X-Environment: production'

Через тело (spawn-kyc для UBO)¶

curl -X POST 'https://api.compliance.example/v1/applicants/acme-corp/ubos/0/spawn-kyc' \
  -H 'X-Api-Key: pk_live_...' \
  -H 'X-Api-Secret: ...' \
  -H 'X-Environment: production' \
  -H 'Content-Type: application/json' \
  -d '{
        "ttlDays": 14,
        "lang": "ru",
        "theme": "dark",
        "returnUrl": "https://acme.com/ubo-done"
      }'

Замечания¶

Пользователь может переопределить lang и theme уже внутри SDK (переключатель языка в шапке, тема стартует с переданной, но поддаётся изменению). Передаваемые параметры — это значения по умолчанию, а не блокировка.
Серверная сторона не проверяет URL редиректов по списку разрешённых доменов — достаточно, чтобы строка парсилась как валидный абсолютный http(s) URL. Не передавайте сюда URL, полученные от конечного пользователя, без собственной валидации.
Все четыре URL-поля проходят один и тот же парсер. Если случайно передать returnUrl=javascript:… или относительный путь, поле молча отбрасывается, и SDK остаётся на финальном экране.