Формат работы с API
Версия API
В настоящее время мы поддерживаем две версии API для некоторых методов.
Пожалуйста, используйте правильные наименования объектов для каждой версии!
API v1 | API v2 |
---|---|
payment_method | payout_details |
payments | payout_list |
acquiring_payments | payment_list |
Методы, поддерживаемые в API v2
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
fps/customer_verification
session/status
session/init/payout/nominal
session/multi/create/nominal
session/multi/init/payment/nominal
session/multi/start/payment/nominal
session/init/payout/rko
session/multi/create/rko
session/multi/start/payment/rko
Адрес для отправки запросов
Как сформировать
<адрес сервера> + /api/v{номер версии API} + <адрес для отправки запросов нужного метода>
Например:
API v1: https://demo.bank131.ru/api/v1/session/init/payout
API v2: https://demo.bank131.ru/api/v2/session/init/payout
Адрес сервера
- Для тестирования
https://demo.bank131.ru
- Для реальных операций
https://proxy.bank131.ru
Формат запросов
Все данные в запросах к Банку 131 и уведомлениях от Банка передаются методами POST и GET по протоколу 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: signature' \
-d '{
// тело запроса
}'
Подпись запроса
Подпись нужна, чтобы проверять подлинность и целостность запросов. Банк 131 проверяет, что запросы пришли именно от вас (и дошли целиком), вы проверяете таким же образом уведомления от банка.
Для формирования и проверки подписи нужен публичный и секретный ключ. Ваш публичный ключ указывается в Акте признания ключа проверки электронной подписи С помощью ключа Банк 131 будет проверять подпись ваших входящих запросов.
Генерация ключевой пары
Вам нужно сгенерировать на своей стороне пару ключей с алгоритмом подписи RSA.
Формирование подписи тела запроса
Вместе с запросом в Банк 131 необходимо передавать подпись. Подписывать необходимо тело запроса целиком, в том виде, в котором оно отправляется на сервер Банка (после сериализации тела запроса в JSON для отправки по HTTP).
Используйте для подписи ваш секретный ключ. Сформируйте подпись с алгоритмом SHA-256. Полученную подпись необходимо передавать в формате Base64.
Проверка входящих запросов от Банка 131
Все исходящие запросы Банк 131 подписывает с помощью своего секретного ключа.
С помощью публичного ключа Банка 131 вам необходимо проверять подписи запросов от Банка на своей стороне. Используется алгоритм SHA-256. Подпись передается в формате Base64.
Публичный ключ Банка 131
Примеры генерации и проверки подписи
- OpenSSL
- PHP
# Генерация приватного ключа
$ 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);
Ключ идемпотентности
Ключ идемпотентности - это уникальный идентификатор операции. Вы можете его самостоятельно генерировать и использовать, когда есть необходимость запретить повторное выполнение той же операции до её завершения. Например, чтобы не сделать двойную выплату или списание.
Срок действия ключа составляет 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: signature' \
-H 'X-PARTNER-IDEMPOTENCY-KEY: testkey' \
-d '{
// тело запроса
}'
Список методов с поддержкой ключа идемпотентности
Список возможных ошибок
- idempotency_key_params_mismatch - Ключ уже был использован ранее для другой сессии.
- idempotency_key_already_exists - Предыдущий запрос с таким же ключом еще не обработан.
- idempotency_key_not_supported - Метод не поддерживает использование ключа идемпотентности.
Больше об Ошибках
Библиотеки
Библиотеки, которые вы можете использовать для интеграции по API Банка 131.