KYC события

Вебхуки для отслеживания результатов верификации

KYC события

Love&Pay отправляет вебхуки о результатах KYC верификации.

Доступные события

Событие	Описание
kyc.completed	Верификация успешно завершена
kyc.failed	Верификация не пройдена

kyc.completed

Отправляется при успешном прохождении KYC верификации.

{
  "id": "evt_kyc001",
  "type": "kyc.completed",
  "createdAt": "2024-01-15T14:00:00Z",
  "data": {
    "session": {
      "id": "kyc_abc123def456",
      "level": "basic",
      "status": "completed",
      "verifiedData": {
        "firstName": "Иван",
        "lastName": "Петров",
        "dateOfBirth": "1990-05-15",
        "nationality": "RU",
        "documentType": "passport",
        "documentNumber": "****5678"
      },
      "metadata": {
        "userId": "user_12345",
        "email": "[e-mail]"
      },
      "createdAt": "2024-01-15T10:30:00Z",
      "completedAt": "2024-01-15T14:00:00Z"
    }
  }
}

kyc.failed

Отправляется при неудачной KYC верификации.

{
  "id": "evt_kyc002",
  "type": "kyc.failed",
  "createdAt": "2024-01-15T14:00:00Z",
  "data": {
    "session": {
      "id": "kyc_abc123def456",
      "level": "basic",
      "status": "failed",
      "failureReason": "document_expired",
      "failureDetails": "Срок действия документа истёк. Пожалуйста, используйте действующий документ.",
      "metadata": {
        "userId": "user_12345",
        "email": "[e-mail]"
      },
      "createdAt": "2024-01-15T10:30:00Z",
      "failedAt": "2024-01-15T14:00:00Z"
    }
  }
}

Обработка KYC событий

Node.js

app.post('/webhooks/loveandpay', (req, res) => {
  // Верификация подписи (см. раздел Верификация подписи)

  const event = req.body;

  switch (event.type) {
    case 'kyc.completed':
      handleKycCompleted(event.data.session);
      break;
    case 'kyc.failed':
      handleKycFailed(event.data.session);
      break;
  }

  res.status(200).json({ received: true });
});

async function handleKycCompleted(session) {
  const userId = session.metadata.userId;

  // Обновляем статус пользователя в базе
  await db.users.update({
    where: { id: userId },
    data: {
      kycStatus: 'verified',
      kycLevel: session.level,
      kycVerifiedAt: session.completedAt,
      // Сохраняем верифицированные данные
      firstName: session.verifiedData.firstName,
      lastName: session.verifiedData.lastName,
      dateOfBirth: session.verifiedData.dateOfBirth
    }
  });

  // Отправляем уведомление пользователю
  await sendEmail(session.metadata.email, 'kyc-success', {
    firstName: session.verifiedData.firstName
  });

  console.log(`KYC пройден для пользователя ${userId}`);
}

async function handleKycFailed(session) {
  const userId = session.metadata.userId;

  // Обновляем статус
  await db.users.update({
    where: { id: userId },
    data: {
      kycStatus: 'failed',
      kycFailureReason: session.failureReason
    }
  });

  // Уведомляем пользователя о необходимости повторной верификации
  await sendEmail(session.metadata.email, 'kyc-failed', {
    reason: session.failureDetails
  });

  console.log(`KYC не пройден для пользователя ${userId}: ${session.failureReason}`);
}

Рекомендации

Используйте metadata

Передавайте userId и другие идентификаторы в metadata для связи с вашей системой

Обрабатывайте оба события

Всегда обрабатывайте как успешные, так и неудачные верификации

Уведомляйте пользователей

Информируйте пользователей о результате верификации по email

Предлагайте повтор

При неудаче предложите пользователю пройти верификацию повторно

Причины отказа

Код	Описание	Рекомендация пользователю
document_expired	Документ просрочен	Используйте действующий документ
document_unreadable	Плохое качество фото	Сделайте чёткое фото при хорошем освещении
document_mismatch	Данные не совпадают	Проверьте правильность введённых данных
selfie_mismatch	Лицо не распознано	Снимите очки, головной убор, обеспечьте хорошее освещение
suspected_fraud	Подозрение на мошенничество	Свяжитесь со службой поддержки
unsupported_document	Тип документа не поддерживается	Используйте паспорт или ID-карту