Перейти к основному содержимому

Проверка бенефициаров перед выплатой

В целях безопасности Банк 131 обязан идентифицировать бенефициаров по номинальному счету. Через API можно проверить только бенефициаров-физических лиц, являющихся резидентами-получателями. Для проверки прочих бенефициаров данные необходимо передать Банку в excel-файле любым удобным способом.

Идентификация через API​

Адрес сервера​

Для тестирования операций: https://kyc-stage.bank131.ru/

Для операций с реальными данными: https://kyc.bank131.ru/

Посмотреть правила оформления запросов >

Подписание запросов​

Предварительно настройте УКЭП:

  1. Получите усиленную квалифицированную электронную подпись (УКЭП) в любом удостоверяющем центре. Нерезиденты РФ могут использовать RSA.

    Для тестирования можете создать сертификат в Тестовом УЦ КриптоПро.

  2. Установите КриптоПро CSP и добавьте сертификат в хранилище (например, по инструкции для Windows).
  3. Предоставьте Банку 131 список IP-адресов, с которых будете отправлять запросы.
  4. Передайте публичный ключ подписи персональному менеджеру Банка 131 для идентификации ваших запросов.

После настройки подписывайте каждый запрос следующим образом:

  1. Возьмите содержимое payload, отсортируйте ключи по алфавиту и запишите в файл, используя кодировку UTF-8.
Пример записи содержимого payload в файл
import json

payload = {...}

payload_bytes = bytes(json.dumps(payload, sort_keys=True) + '\r\n', encoding='utf-8')

with open('payload_bytes.jsonb', 'wb') as f:
    f.write(payload_bytes)

  1. Подпишите файл с помощью КриптоПро CSP (например, утилитой cryptcp).
Пример подписания файла
cryptcp -sign -display -thumbprint <отпечаток_ключа_для_подписи> -detached payload_json.json payload_json.sig
  1. Передайте содержимое файла подписи (payload_json.sig) в параметре signature запроса.

Отправка данных на проверку​

Отправьте запрос check с данными физического лица. В ответе вы получите идентификатор заявки. По нему можно узнать результат проверки.

Параметры запроса​

НазваниеОбязательностьТипОписание
type+stringТип получателя: FL_RESIDENT
last_name+stringФамилия
first_name+stringИмя
patronymic-stringОтчество
birthday+stringДата рождения в формате: ДД.ММ.ГГГГ. Получатель должен быть старше 18-ти лет
birthplace+stringМесто рождения
citizenship+stringГражданство в формате: ISO 3166-1 alpha-2
inn+stringИНН: 12 цифр
phone_number+stringНомер телефона в любом формате
email+stringДействующий адрес электронной почты
documents+arrayПаспорт РФ: PASSPORT_RF
  type+stringТип документа: PASSPORT_RF — паспорт РФ
  number+stringСерия и номер паспорта в формате: 1234567890
  issuer+stringКем выдан
  issuer_date+stringДата выдачи в формате: ДД.ММ.ГГГГ
  issuer_code+stringКод подразделения
address+stringАдрес регистрации
postcode-stringПочтовый индекс
agent_contract_number+stringНомер агентского договора с получателем
agent_contract_date+stringДата агентского договора с получателем в формате: ДД.ММ.ГГГГ. Дата должна быть меньше или равна текущей дате
beneficial_owners+stringСведения о бенефициарных владельцах: БВ отсутствуют
public_officials+stringПринадлежность к ПДЛ: Нет
Пример запроса
curl -X POST \
  https://kyc.bank131.ru/api/v2/check \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-PROJECT: your_project_name' \
  -H 'X-PARTNER-SIGN: signature' \
  -d '{
    "type": "FL_RESIDENT",
    "last_name": "Иванов",
    "first_name": "Иван",
    "patronymic": "Иванович",
    "birthday": "01.01.1970",
    "birthplace": "г. Новгород",
    "citizenship": "RU",
    "inn": "065553161159",
    "phone_number": "+79000000000",
    "email": "name@email.com",
    "documents": [{
      "type": "PASSPORT_RF ",
      "number": "0234567890",
      "issuer": "ОТДЕЛОМ УФМС РОССИИ",
      "issuer_date": "01.01.2010",
      "issuer_code": "123-000"
    }],
    "address": "г. Новгород, алл. Прибрежная, д. 53 стр. 9",
    "postcode": "365826",
    "agent_contract_number": "123456789-0",
    "agent_contract_date": "01.01.2020",
    "beneficial_owners": "БВ отсутствуют",
    "public_officials": "Нет"
  }'

Параметры ответа​

НазваниеОбязательностьТипОписание
status+stringСтатус идентификации. Возможные варианты: ok, error
data-DataДанные ответа
  id-numberИдентификатор запроса check
  description-stringОписание статуса запроса
error-ErrorДанные ошибки
  code+stringКод ошибки
  description+stringОписание ошибки
Примеры ответов
{
  "status": "ok",
  "data": {
    "id": "7",
    "description": "запрос добавлен в очередь"
  }
}
Параметры ответа на тестовый запрос

При тестировании результат проверки (значение status в ответе) определяется последней цифрой номера паспорта в параметре passport_number.

Последняя цифра passport_numberЗначение status
Четный, включая 0ok
Нечетныйerror

Результат проверки​

Чтобы узнать результат проверки, используйте метод check/{id}. Укажите в запросе идентификатор, полученный в ответе на запрос check. Обработка результата может занять от 10 минут до 2 суток.

Параметры запроса​

Тело запроса пустое.

Пример запроса
curl -X GET \
  https://kyc.bank131.ru/api/v2/check/7 \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-PROJECT: your_project_name' \

Параметры ответа​

НазваниеОбязательностьТипОписание
status+stringСтатус идентификации. Возможные варианты: ok, pending, error
data-objectДанные ответа
  id-numberИдентификатор запроса check
  description-stringОписание статуса запроса
error-objectДанные ошибки
  code+stringКод ошибки
  description+stringОписание ошибки
Примеры ответов
{
  "status": "ok",
  "data": {
    "id": "7", // идентификатор запроса `check`
    "description": "valid"
  }
}

Статусы и коды ошибок​

HTTP-коды ответа​

КодЗначениеРешение
200Запрос сформирован правильноСмотрите параметр status
422Ошибка в запросеСмотрите параметр error.description:
- request_body_validation_error — ошибка в теле запроса;
- request_header_validation_error — отсутствует заголовок x-partner-project
500Ошибка на стороне Банка 131Повторите запрос позже

Статусы ответа​

Статусы ответа возвращаются в параметре status.

СтатусЗначениеРешение
okЗапрос выполнен успешноСмотрите объект data
pendingЗапрос в обработкеЧтобы узнать результат, повторите запрос позже
errorОшибка в результате обработки запросаСмотрите объект error

Коды ошибок​

Ошибки возвращаются в объекте error:

  • code — код ошибки;
  • description — описание ошибки.
КодОписаниеВариант решения
invalid_signЗапрос с указанным идентификатором подписан некорректноПроверьте формирование подписи запроса
passport_validation_failureВ базе данных МВД отсутствуют сведения о предоставленном паспортеПроверьте паспортные данные
passport_validation_failureПо данным МДВ предоставленный паспорт признан недействительнымПроверьте паспортные данные
inn_validation_failureПо данным ФНС предоставленный паспорт не соответствует предоставленному ИННПроверьте ИНН
already_existsЗапрос на проверку с теми же данными был направлен ранееВы уже отправляли эти данные на идентификацию. Чтобы узнать результат, отправьте запрос check{id} с идентификатором предыдущей проверки из параметра data.id
request_not_foundНе найден запрос с указанным идентификаторомЗапрос на проверку с этим идентификатором не найден. Проверьте идентификатор
partner_project_not_foundВозраст проверяемого лица ниже допустимого порогаИдентификатора проекта, отправленного в заголовке X-PARTNER-PROJECT, не существует. Проверьте идентификатор
birthday_validation_failureВозраст получателя ниже допустимого порогаПроверяемый должен быть совершеннолетним. Если вы получили эту ошибку при работе с номинальным счетом, обратитесь к персональному менеджеру
validation_errorЗапрос не прошел валидацию. Например: 1 validation error for Request.body → payload → documents → 2 → expire_date. Document MIGRATION_CARD is expired (type=value_error)Ошибки формата или проверки передаваемых значений. Подробное описание передается в параметре description
Примеры ответов с ошибками
{
  "status": "error",
  "error": {
    "code": "passport_validation_failure",
    "description": "По данным МДВ предоставленный паспорт признан недействительным"
  }
}