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

Формат работы с API

Формат запросов​

Все данные в запросах к Банку 131 и уведомлениях от Банка передаются методами POST или GET по протоколу HTTP. Параметры сообщения упаковываются в JSON-объект.

В настоящее время поддерживаются две версии метода идентификации бенефициаров, но так как версия 1.1 больше не получает обновлений, мы рекомендуем использовать версию 2.0.

Адрес для отправки запросов​

Как сформировать​

<адрес сервера> + /api/v2.0/ + <адрес для отправки запросов нужного метода>

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

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

Аутентификация​

В заголовках запросов к Банку 131 необходимо передавать идентификатор вашего проекта.

Заголовки​

НазваниеОбязательностьТипОписание
X-PARTNER-PROJECT+stringИдентификатор проекта. Выдается менеджером Банка 131
Пример запроса с аутентификацией 
curl -X GET \
https://kyc.bank131.ru/api/v2.0/check/7 \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-d '{
  // тело запроса
}'

Подпись запросов​

В запросах на идентификацию отправляются персональные данные, поэтому требуется подписывать запросы с помощью КриптоПро.
Для нерезидентов РФ есть возможность подписи запроса через алгоритм RSA. Для подключения данной возможности обратитесь к вашему менеджеру в Банке 131.

Что нужно для работы с КриптоПро​

  1. Получить усиленную квалифицированную электронную подпись (УКЭП), если у вас ее нет. Это можно сделать в любом удостоверяющем центре.

    Для тестирования можно создать сертификат ключа идентификации электронной подписи в Тестовом удостоверяющем центре КриптоПро, но для реальных операций он не подойдет.

  2. Установить КриптоПро CSP на свой компьютер.

  3. Добавить в КриптоПро сертификат своей электронной подписи (вот, для примера, инструкция для Windows).

  4. Предоставить Банку список IP-адресов, с которых вы планируете отправлять запросы.

  5. Отправить публичную часть ключа электронной подписи вашему менеджеру в Банке 131 (чтобы мы могли идентифицировать ваши запросы).

Готово, теперь вы можете подписывать запросы с помощью КриптоПро.

Как подписывать запросы​

Шаг 1. Создайте файл для подписи​

Возьмите тело запроса (содержимое payload), отсортируйте по ключам и запишите в файл. Используйте кодировку UTF-8.

Пример 
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)

Шаг 2. Подпишите файл​

Подпишите файл средствами КриптоПро. Например, с помощью приложения cryptcp (входит в КриптоПро).

Пример создания подписи 
cryptcp -sign -display -thumbprint <отпечаток_ключа_для_подписи> -detached payload_json.json payload_json.sig

Шаг 3. Добавьте в запрос подпись​

Заберите получившуюся подпись из файла payload_json.sig и передайте в запросе — в поле signature.