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

# Генерация приватного ключа
$ 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

PHP

$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);

Ключ идемпотентности

Ключ идемпотентности - это уникальный идентификатор операции. Вы можете его самостоятельно генерировать и использовать, когда есть необходимость запретить повторное выполнение той же операции до её завершения. Например, чтобы не сделать двойную выплату или списание.

Срок действия ключа составляет 24 часа.

Формат

Идентификатор ключа идемпотентности указывается в заголовке запроса.

Название	Обязательность	Тип	Описание
X-PARTNER-IDEMPOTENCY-KEY	-	string	Ключ идемпотентности. Формат: от 4 до 64 знаков

Пример запроса с ключом идемпотентности

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' \
  -H 'X-PARTNER-IDEMPOTENCY-KEY: testkey' \
  -d '{
    // тело запроса
}'

Список методов с поддержкой ключа идемпотентности

• session/create
• session/init/payout
• session/init/payout/fiscalization
• session/start/payout
• session/start/payout/fiscalization
• session/init/payment
• session/init/payment/sync
• session/start/payment
• session/confirm
• session/capture
• session/cancel
• session/refund

Список возможных ошибок

• idempotency_key_params_mismatch - Ключ уже был использован ранее для другой сессии
• idempotency_key_already_exists - Предыдущий запрос с таким же ключом еще не обработан
• idempotency_key_not_supported - Метод не поддерживает использование ключа идемпотентности

Больше об Ошибках

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

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