Формат работы с API
Адрес для отправки запросов
Как сформировать
<адрес сервера> + /api/v{номер версии API} + <адрес для отправки запросов нужного метода>
Номер версии указывается до точки. Текущую версию можно посмотреть в Истории изменений или на страницах компонентов API.
Например, если версия Массовых выплат 1.8
, адрес для запроса на тестовую выплату
будет выглядеть так:
https://demo.bank131.ru/api/v1/session/init/payout
Адрес сервера
- Для тестирования
https://demo.bank131.ru
- Для реальных операций
https://proxy.bank131.ru
Формат запросов
Все данные в запросах к Банку 131 и уведомлениях от Банка передаются методом POST по протоколу HTTP. Параметры сообщения упаковываются в JSON-объект.
Аутентификация
В заголовках запросов к Банку необходимо передавать данные для идентификации: идентификатор вашего проекта и подпись запроса.
Аутентификация
Название | Обязательность | Тип | Описание |
---|---|---|---|
X-PARTNER-PROJECT | + | string | Идентификатор проекта. Выдается менеджером Банка 131 |
X-PARTNER-SIGN | + | string | Подпись запроса (см. ниже) |
X-PARTNER-SUBMERCHANT | - (обязательно для финансовых организаций, являющихся нерезидентами РФ) | string | Идентификатор плательщика (юридического лица) |
Пример запроса с аутентификацией
curl -X POST \
https://demo.bank131.ru/api/v1/session/create \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: sign' \
-d '{
// тело запроса
}'
Подпись запроса
Подпись нужна, чтобы проверять подлинность и целостность запросов. Банк 131 проверяет, что запросы пришли именно от вас (и дошли целиком), вы проверяете таким же образом уведомления от банка.
Для формирования и проверки подписи нужен публичный и секретный ключ. Ваш публичный ключ указывается в заявлении о признании и сверке ключа электронной подписи С помощью ключа Банк 131 будет проверять подпись ваших входящих запросов.
Генерация ключевой пары
Вам нужно сгенерировать на своей стороне пару ключей с алгоритмом подписи RSA.
Формирование подписи тела запроса
Вместе с запросом в Банк 131 необходимо передавать подпись. Подписывать необходимо тело запроса целиком, в том виде, в котором оно отправляется на сервер Банка (после сериализации тела запроса в JSON для отправки по HTTP).
Используйте для подписи ваш секретный ключ. Сформируйте подпись с алгоритмом SHA-256. Полученную подпись необходимо передавать в формате Base64.
Проверка входящих запросов от Банка 131
Все исходящие запросы Банк 131 подписывает с помощью своего секретного ключа.
С помощью публичного ключа Банка 131 вам необходимо проверять подписи запросов от Банка на своей стороне. Используется алгоритм SHA-256. Подпись передается в формате Base64.
Публичный ключ Банка 131:
Примеры генерации и проверки подписи
# Генерация приватного ключа
$ openssl genrsa -out private.pem 2048
# Генерация публичного ключа из приватного
$ openssl rsa -in private.pem -pubout > public.pem
# Формирование содержимого файла myfile.txt
$ echo test > myfile.txt
# Генерация подписи
$ openssl dgst -sha256 -sign private.pem -out sha256.sign myfile.txt
# Готовая подпись для передачи
$ base64 sha256.sign
# Проверка подписи
$ openssl dgst -sha256 -verify public.pem -signature sha256.sign myfile.txt
Verified OK
$data = "test";
//Получение указателя на приватный и публичный ключи
$privateKey = openssl_pkey_get_private("file://private.pem");
$publicKey = openssl_pkey_get_public("file://public.pem");
//Генерация подписи по данным с использованием приватного ключа
openssl_sign($data, $signature, $privateKey, OPENSSL_ALGO_SHA256);
openssl_free_key($privateKey);
//Для передачи подпись кодируем в формат Base64
$base64Signature = base64_encode($signature);
//При получении подписи декодируем ее обратно из Base64
$decodedSignature = base64_decode($base64Signature);
//Проверяем полученную подпись с использованием публичного ключа (1 - успех)
$isValid = openssl_verify($data, $decodedSignature, $publicKey, OPENSSL_ALGO_SHA256);