mdМаркдаун jsonСхема ручек

KYC (Know Your Customer)

KYC — верификация конечного клиента мерчанта (того кто платит). Не мерчанта. Нужен только для:

• Платежей на суммы выше настроенного порога (если настроено);
• Обменов (/exchanges) в обе стороны — USDT↔RUB;
• Некоторых категорий мерчантов по решению X-Hub.

Если твой аккаунт не требует KYC — пропусти этот раздел. Все три KYC-эндпоинта вернут {"status": "not_required"} или 400 KYC_NOT_REQUIRED.

Два способа интеграции KYC

У мерчанта два варианта — выбери один:

Способ 1: Hosted redirect (простой)

X-Hub предоставляет готовую страницу верификации. Мерчант перенаправляет своего клиента туда, клиент заполняет форму (телефон, селфи, паспорт, адрес), после верификации возвращается на сайт мерчанта.

https://app.x-hub.online/kyc?phone=+79001234567&redirect=https://your-site.com/kyc-done

Query-параметры:

Параметр	Обяз.	Описание
phone	—	Телефон клиента в формате +7XXXXXXXXXX (можно не передавать — клиент введёт сам)
redirect	—	URL, куда вернуть клиента после завершения. Только HTTPS, только same-origin с твоим доменом. Если не указан — редирект на /

Плюсы: ничего не надо писать на стороне мерчанта. Минусы: клиент уходит с твоего сайта, меньше контроля над UX.

Способ 2: API-first (встроенный в UI мерчанта)

Мерчант делает KYC-форму внутри своего приложения (свой UI, свой дизайн), а вызывает наши API для загрузки документов и регистрации. Клиент не покидает сайт мерчанта.

Flow (со стороны backend мерчанта):

1. POST /v1/kyc/check → проверить, нужен ли KYC и не пройден ли уже;
2. POST /v1/kyc/upload-url × 3 → получить signed URL на селфи / паспорт / адрес;
3. Фронтенд мерчанта загружает файлы напрямую на upload URL (PUT, без прохождения через backend);
4. POST /v1/kyc/register → передать file_key'и + phone;
5. Периодически POST /v1/kyc/check → дождаться status: verified.

Плюсы: полный контроль UX и брендинга. Минусы: больше кода на стороне мерчанта, своя форма загрузки файлов.

Детали всех endpoints — ниже.

Когда нужен KYC

Если при создании платежа вы получаете ошибку:

{ "error": { "code": "KYC_REQUIRED", "message": "..." } }

— значит для вашего аккаунта настроена обязательная KYC-проверка. Используйте flow ниже.

Если ошибки нет

Если при создании платежа вы НЕ получаете KYC_REQUIRED — KYC не требуется. Можете пропустить этот раздел. Все три KYC-эндпоинта вернут {"status": "not_required"} или 400 KYC_NOT_REQUIRED.

Проверить KYC — POST /kyc/check

Проверяет статус KYC-верификации клиента по номеру телефона.

curl -X POST https://api.x-hub.online/api/v1/kyc/check \
  -H "X-Api-Key: ..." -H "X-Api-Secret: ..." \
  -H "Content-Type: application/json" \
  -d '{"phone": "+79991234567"}'

Body

Поле	Тип	Обяз.	Описание
phone	string	✓	Телефон клиента в формате +7XXXXXXXXXX

Ответы

KYC не требуется (для вашего аккаунта не настроен):

{"status": "not_required"}

KYC верифицирован:

{"status": "verified", "accountNumber": "..."}

KYC не пройден (нужна регистрация):

{"status": "required", "kyc_url": "https://..."}

KYC в обработке:

{"status": "processing"}

KYC отклонён:

{"status": "failed", "error": "..."}

Ошибки KYC-эндпоинтов

Одинаковы для всех трёх (/kyc/check, /kyc/upload-url, /kyc/register):

HTTP	Code	Причина	Что делать
400	SANDBOX_NOT_SUPPORTED	KYC в песочнице недоступен для конфигурации твоего аккаунта	Тестируй KYC в боевом режиме или напиши в X-Hub
400	KYC_NOT_REQUIRED	KYC для аккаунта не настроен (/upload-url, /register). У /kyc/check тот же случай даёт 200 {"status":"not_required"}	Просто создавай платежи, KYC не нужен
400	VALIDATION_ERROR	Невалидный phone / content_type / состав ключей файлов	Проверь формат
403	PROVIDER_DISABLED	KYC для твоего аккаунта отключён. Отдаётся до любой другой проверки — то есть даже валидный запрос получит 403	Это не ошибка запроса и не «не пройден KYC». Ретрай не поможет: напиши в X-Hub
502	PROVIDER_ERROR	Проверяющая сторона не ответила (сеть, таймаут, её 5xx)	Временная ошибка. Ретрай через 30–60 сек
503	KYC_UNAVAILABLE	Твоему аккаунту KYC положен, но верификация сейчас недоступна на нашей стороне (внутренняя неполадка X-Hub, не твоей интеграции)	Это не «KYC не нужен» — не пропускай верификацию клиента. Ретрай через 1–2 минуты; если долго — напиши в X-Hub
500	KYC_PERSIST_FAILED	Только на /kyc/register: проверяющая сторона клиента уже приняла, но у нас не сохранилась запись об этом — сбой уже ПОСЛЕ успешного шага верификации	Не повторяй запрос с теми же данными. Напиши в X-Hub с временем запроса и телефоном/e-mail клиента — восстановим вручную

403 PROVIDER_DISABLED легко спутать с отказом в верификации

Это не «клиент не прошёл KYC» — отказ по клиенту приходит как {"status": "failed"} с 200. 403 PROVIDER_DISABLED означает, что KYC для твоего аккаунта отключён, и ни один клиент верифицироваться не сможет. Если он появился внезапно — не переписывай интеграцию, сначала спроси команду X-Hub.

503 KYC_UNAVAILABLE — тоже не «KYC не нужен»

Если твой аккаунт настроен на KYC, KYC_NOT_REQUIRED / {"status":"not_required"} ты в норме никогда не увидишь. 503 KYC_UNAVAILABLE значит ровно обратное: KYC нужен, но сейчас сломан на нашей стороне. Не интерпретируй его как разрешение пропустить верификацию клиента.

Получить URL для загрузки документов — POST /kyc/upload-url

Получает pre-signed URL для загрузки документов KYC (фото паспорта, селфи).

curl -X POST https://api.x-hub.online/api/v1/kyc/upload-url \
  -H "X-Api-Key: ..." -H "X-Api-Secret: ..." \
  -H "Content-Type: application/json" \
  -d '{"content_type": "image/jpeg"}'

Body

Поле	Тип	Обяз.	Описание
content_type	string	✓	MIME-тип файла (image/jpeg, image/png, application/pdf)

Ответ

{
  "upload_url": "https://storage.example.com/...",
  "file_key": "kyc/abc123..."
}

Загрузи файл по upload_url (PUT), затем используй file_key в POST /kyc/register.

Зарегистрировать KYC — POST /kyc/register

Отправляет данные KYC-верификации в X-Hub.

curl -X POST https://api.x-hub.online/api/v1/kyc/register \
  -H "X-Api-Key: ..." -H "X-Api-Secret: ..." \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+79991234567",
    "selfie_key": "kyc/selfie-abc123",
    "document_key": "kyc/doc-def456",
    "address_key": "kyc/addr-ghi789"
  }'

Body

Поле	Тип	Обяз.	Описание
phone	string	✓	Телефон клиента в формате +7XXXXXXXXXX. Единственное поле, обязательное всегда
selfie_key	string	*	file_key от upload-url (селфи)
document_key	string	*	file_key от upload-url (документ)
address_key	string		file_key от upload-url (подтверждение адреса)
email	string	*	E-mail клиента
user_type	string	*	individual или legal_entity

Какие из полей со звёздочкой нужны — зависит от KYC-конфигурации аккаунта

Конфигураций две, и обязательный набор у них разный:

• загрузка документов — нужны selfie_key + document_key (плюс опционально address_key);
• переадресация клиента на форму верификации — нужны email + user_type, файлы не нужны; в ответе придёт {"status": "required", "kycUrl": "..."}, и клиента надо отправить по этому адресу.

Валидация тела не проверяет комбинацию: запрос без нужных полей пройдёт схему и упрётся уже в проверяющую сторону (502 PROVIDER_ERROR или отказ по клиенту). Какая конфигурация у тебя — уточни при подключении.

Ответ

{"status": "processing"}

Либо {"status": "required", "kycUrl": "..."} — если клиента нужно отправить на форму верификации, либо {"status": "verified", "accountNumber": "..."} — если он уже верифицирован.

Повторный register по тому же телефону безопасен

Если клиент уже верифицирован (или ему уже выдана ссылка на верификацию), повторный вызов вернёт сохранённый результат, не запуская проверку заново. Исключение — клиент, которому ранее отказали: такой запрос уйдёт на новую проверку.

Исключение — 500 KYC_PERSIST_FAILED: это НЕ тот безопасный повтор

Если ответ — 500 KYC_PERSIST_FAILED, «сохранённого результата» из подсказки выше ещё нет: у нас не записалась информация о том, что клиент уже прошёл шаг верификации. Слепой повтор register с теми же данными может уйти в новую попытку регистрации у проверяющей стороны — для части конфигураций это ломает саму возможность зарегистрировать клиента повторно. Не повторяй — пиши в X-Hub.

После регистрации — периодически проверяй статус через POST /kyc/check.

Интеграция KYC + платежи

Если для вашего аккаунта требуется KYC, при создании платежа передавай client_phone:

curl -X POST https://api.x-hub.online/api/v1/payments \
  -H "X-Api-Key: ..." -H "X-Api-Secret: ..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_rub": "500.00",
    "payment_method": "sbp",
    "client_phone": "+79991234567"
  }'

Если KYC не пройден, API вернёт:

• 400 KYC_REQUIRED — клиент не верифицирован
• 400 KYC_PROCESSING — верификация в процессе, попробуй позже
• 400 KYC_FAILED — верификация отклонена

---