04 kyc

KycEndpoint — 7 методов для прохождения KYC.

Доступ

Все методы: requireAccountType(session, ['wallet']). Только wallet-аккаунты проходят KYC. Consumer (closeloop) и merchant/agent не используют этот endpoint.

Методы

Метод	Параметры	Возвращает	Статус KYC после
initializeKyc(documentFrontUrl, documentBackUrl, selfieUrl)	три S3 URL документов	KycVerification	ocr_pending
submitForReview()	—	void	in_review (kyc-service job fired)
getOcrResult()	—	KycOcrResult? — null если ещё не готово	читать только при ocr_complete
confirmKycData(fullName, dateOfBirth, nationality, countryOfResidence, nationalIdNumber, address, dateOfIssue, dateOfExpiry, gender, phone, languageCode)	11 полей, подтверждённых пользователем	void	pending_operator_review
retryKycProcessing()	—	bool — true если job переотправлен	ocr_pending (повторная очередь); только при ocr_failed
getFailureReason()	—	String? — 'invalid_passport' / 'invalid_selfie' / 'processing_error'	не меняет статус
getKycStatus()	—	String? — текущий KYC-статус	не меняет статус

Порядок вызовов (нормальный flow)

1. initializeKyc(frontUrl, backUrl, selfieUrl) — загрузить S3 URL документов, создать запись KYC
2. submitForReview() — отправить job в kyc-service (BullMQ) для OCR
3. Поллинг getKycStatus() до ocr_complete или ocr_failed
4. Если ocr_failed: getFailureReason() → показать ошибку, затем retryKycProcessing() → переход к шагу 3
5. getOcrResult() — получить OCR-данные (доступно при ocr_complete)
6. Показать пользователю данные OCR для подтверждения/корректировки
7. confirmKycData(...) — пользователь подтверждает/корректирует 11 полей, PII шифруется через PiiProfileWriter
8. Статус → pending_operator_review, далее ожидание действий оператора в AdminKycEndpoint

Важно

• URL документов (S3) передаются в initializeKyc — Auth Center их не скачивает и не хранит в БД, только записывает ключ. Реальные файлы живут в S3.
• confirmKycData проверяет profile.isLocked — если профиль заблокирован, вызов отклоняется.
• retryKycProcessing работает только при status=ocr_failed. При других статусах возвращает false.
• getFailureReason возвращает значение только при status=ocr_failed, иначе null.