Фото паспорта и селфи при создании картхолдера

Обзор

После создания картхолдера вы можете загрузить фотографию паспорта и селфи с паспортом через отдельный эндпоинт. Эти фото хранятся в PayCA и используются администраторами для верификации при одобрении картхолдера. Фото не передаются карточному провайдеру.

Загрузка фото опционально — картхолдер может быть одобрен и без них. Однако наличие фото ускоряет процесс одобрения администратором.

Требования к фото

Параметр	Значение
Формат	JPEG или PNG
Максимальный размер	5 МБ на файл
Тип запроса	`multipart/form-data`

Эндпоинт

POST /v1/cardholders/{id}/photos
Content-Type: multipart/form-data

Загрузите одно или оба фото как файлы в multipart-запросе. Хотя бы одно фото должно быть приложено.

Поля формы

Поле	Тип	Обязательное	Описание
`passportPhoto`	file (binary)	Нет*	Фото паспорта в формате JPEG или PNG. Максимум 5 МБ.
`selfiePhoto`	file (binary)	Нет*	Селфи с паспортом в формате JPEG или PNG. Максимум 5 МБ.

* Хотя бы одно из двух полей должно быть заполнено.

Пример запроса

# Загрузка обоих фото
curl -s -X POST "$PAYCA_BASE_URL/v1/cardholders/{cardholderId}/photos" \
  -H "x-client-id: $PAYCA_CLIENT_ID" \
  -H "x-client-secret: $PAYCA_CLIENT_SECRET" \
  -F "passportPhoto=@passport.jpg" \
  -F "selfiePhoto=@selfie.jpg"

# Загрузка только фото паспорта
curl -s -X POST "$PAYCA_BASE_URL/v1/cardholders/{cardholderId}/photos" \
  -H "x-client-id: $PAYCA_CLIENT_ID" \
  -H "x-client-secret: $PAYCA_CLIENT_SECRET" \
  -F "passportPhoto=@passport.jpg"

Пример ответа

{
  "ok": true
}

Порядок действий

Создайте картхолдера: POST /v1/users/{userId}/cardholder
Загрузите фото: POST /v1/cardholders/{cardholderId}/photos
Дождитесь одобрения (poll GET /v1/cardholders/{id} или подпишитесь на вебхук)
Выпустите карту: POST /v1/cards

Фото можно загрузить в любой момент после создания картхолдера, в том числе после одобрения.

Ошибки валидации

Ошибка	Причина
`passportPhoto exceeds 5MB limit`	Размер файла больше 5 МБ.
`passportPhoto must be JPEG or PNG`	Формат файла не JPEG и не PNG.
`selfiePhoto exceeds 5MB limit`	Размер файла больше 5 МБ.
`selfiePhoto must be JPEG or PNG`	Формат файла не JPEG и не PNG.
`at least one photo ... must be provided`	Ни одно фото не было приложено к запросу.
`cardholder not found`	Картхолдер с указанным ID не найден или принадлежит другому клиенту.

Просмотр фото

Прикреплённые фото доступны администраторам PayCA в Admin UI. При просмотре картхолдера в разделе Cardholders администратор видит фото паспорта и селфи в раскрывающемся блоке при клике на запись картхолдера.

Клиентский API не предоставляет доступа к просмотру загруженных фото — они предназначены только для внутренней верификации.

Примечания

Оба поля полностью опциональны. Вы можете загрузить только passportPhoto, только selfiePhoto или оба сразу.
Повторная загрузка фото перезаписывает предыдущее. Если при повторном запросе передано только одно фото, второе сохраняется без изменений.
Для B2C-картхолдеров, если фото не загружены через этот эндпоинт, система автоматически использует документы из KYC-процесса (если они есть) для отображения в Admin UI.