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

Правила оформления запросов

Для обмена данными API Банка использует формат JSON. Обмен происходит с помощью HTTP-запросов/ответов методами POST и GET.

Версия API​

В настоящее время Банк 131 поддерживает две версии API для некоторых методов. В зависимости от версии используются разные названия для одних и тех же объектов.

Использование неправильных названий может привести к ошибкам выполнения операций.

API v1API v2
payment_methodpayout_details
paymentspayout_list
acquiring_paymentspayment_list
Методы, поддерживаемые в API v2

Адрес для отправки запросов​

Как сформировать​

<адрес сервера> + /api/v{номер версии API} + <адрес для отправки запросов нужного метода>

Адрес сервера​

  • Для тестирования операций — https://demo.bank131.ru
  • Для операций с реальными данными — https://proxy.bank131.ru

Например:

API v1: https://demo.bank131.ru/api/v1/session/init/payout API v2: https://demo.bank131.ru/api/v2/session/init/payout

API-аутентификация​

Каждый раз, когда вы отправляете запрос, вы должны предоставить идентификатор вашего проекта и подпись запроса, чтобы Банк мог вас идентифицировать и убедиться, что запрос пришел именно от вас.

НазваниеОбязательностьТипОписание
X-PARTNER-PROJECT+stringИдентификатор проекта. Выдается менеджером Банка 131
X-PARTNER-SIGN+stringПодпись запроса
X-PARTNER-SUBMERCHANT- (обязательно для финансовых организаций, являющихся нерезидентами РФ)stringИдентификатор плательщика (юридического лица)
Пример запроса с API-аутентификацией 
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 '{
      // тело запроса
  }'

Подпись запроса​

Подпись нужна, чтобы убедиться, что запрос пришел именно от вас, а не от кого-то другого, и не был изменен по пути. Для проверки подписи нужны два ключа: публичный (передается Банку в Акте признания ключа проверки электронной подписи) и секретный (хранится у вас). Банк использует публичный ключ для проверки запросов. Секретный — нужен для подписания ваших запросов, его нельзя никому показывать.

Вам нужно создать эти два ключа, используя алгоритм RSA.

Формирование подписи тела запроса​

Подписать нужно весь запрос целиком, в том виде, в котором он отправляется в Банк (то есть весь текст в формате JSON). Для создания подписи потребуется ваш секретный ключ. Подпись создается с помощью метода шифрования SHA-256. После создания подпись нужно преобразовать в формат Base64, чтобы ее можно было передать вместе с запросом.

Проверка входящих запросов от Банка 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

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

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

Вы сами создаете ключ и отправляете его вместе с запросом. Банк запоминает этот ключ и, если получит запрос с таким же ключом в течение 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 вы можете использовать библиотеку PHP SDK.





ИИ-помощник