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

Формат работы с 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);
 

Публичный ключ Банка 131 для реальных операций​

Скачать публичный ключ