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

# Генерация приватного ключа
$ 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: signature' \
-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 - Метод не поддерживает использование ключа идемпотентности.

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

Библиотеки

Библиотеки, которые вы можете использовать для интеграции по API Банка 131.

PHP SDK