Hasan/alfa-bank-sdk
1
0
Fork 0
forked from apoloz/alfa-bank-sdk
Code Pull Requests Activity
Files
e23e2ea6df9dcaffcfa5ff1ab20f9d053f79d1aa
alfa-bank-sdk/_docs/alfabank/qr_payout/1_main.md

23 KiB
Raw Blame History

Главная

Добро пожаловать на портал с инструкцией по интеграции СБП C2B

Здесь есть вся необходимая информация, которая поможет успешно провести прямую интеграцию с платёжным шлюзом Альфа-Ба

Важное объявление С 1.11.2024 адрес тестового стенда будет изменён на новый URL — https://217.12.103.132:2443/fsCryptoProxy Старые адреса http://217.12.103.147:9914/fsCryptoProxy и https://217.12.103.147:443/fsCryptoProxy станут недоступны В случае если ваши запросы перестанут успешно отрабатываться ПШ банка до 1.11.2024, необходимо заменить URL на новый, не д Для направления запросов на новый URL обязательно устанавливается MTLS соединение В случае если у вас нет ключевой пары для поднятия MTLS соединения на тестовой среде, вам необходимо обратиться в банк по  Информация о том, как направлять запросы с установлением MTLS соединения на тестовой среде, находится по ссылке в разделе

Обзор API

• API позволяет направлять запросы на платёжный шлюз Альфа-Банка (далее — ПШ), чтобы совершать операции с помощью сервис

• Взаимодействие с платёжным шлюзом Альфа-Банка происходит по протоколу HTTPS

• API использует REST-архитектуру, методы POST

• POST-запросы используют JSON-аргументы

• API всегда возвращает ответ в формате JSON

• Ответ от платежного шлюза всегда содержит код ответа — ErrorCode

• Если в процессе обработки запроса произойдёт логическая ошибка, API вернёт её описание в поле message

• Текстовые данные возвращаются в ответе на запрос в формате urlencoded

• Все вопросы по процессу имплементации через данный протокол API можно направлять на адрес сопровождения — acquiring@alfa

Процесс аутентификации

Аутентификация на тестовой среде

Взаимодействие с платёжным шлюзом Альфа-Банка (далее — ПШ) на тестовой среде происходит через интернет по протоколу HTTP

Чтобы установить MTLS-соединение на тестовой среде, банк выдаёт клиенту ключевую пару RSA/TLS: сертификат и приватный клю

MTLS-соединение позволяет произвести двустороннюю аутентификацию.

Внимание

ПШ не обрабатывает запросы с сертификатом MTLS-соединения, по которому истёк срок жизни

Если ПО клиента пытается верифицировать серверный сертификат банка, необходимо добавить в доверенные сертификат удостове

Клиентский самоподписанный сертификат подписывает каждое тело запроса, которое клиент направляет на тестовой среде с помо

Чтобы получить этот сертификат, необходимо самостоятельно сгенерировать ключевую пару client.crt и client.key:

• client.crt — сертификат, который клиент передаёт в банк, чтобы зарегистрировать на тестовой среде

• client.key — приватный ключ, который клиент оставляет у себя, чтобы подписывать тело запроса на тестовой среде

Пример генерации запроса на ключевую пару client.crt и client.key с помощью OpenSSL:

openssl req -x509 -newkey rsa:4096 -keyout private.key -out client.crt -nodes -days 3650

12/23/25, 11:20 AM Главная

https://alfabank.ru/sme/payservice/sbp/docs/welcome/ 1/7

https://alfabank.ru/sme/payservice/sbp/docs/welcome/?rp-menuOpen=1 https://217.12.103.132:2443/fsCryptoProxy http://217.12.103.147:9914/fsCryptoProxy https://217.12.103.147/fsCryptoProxy https://alfabank.ru/sme/payservice/sbp/docs/welcome/?rp-menuOpen=1#authentication_process mailto:acquiring@alfabank.ru

Пример заполнения полей:

• Country Name (2 letter code) []: RU

• State or Province Name (full name) []:

• Locality Name (eg, city) []: Moscow

• Organization Name (eg, company) []: COMPANY

• Organizational Unit Name (eg, section) []: IT

• Common Name (eg, fully qualified host name) []: Company Pay C2B

• Email Address []: admin@test.ru

Примечание

• Длина RSA ключа может быть 2048 или 4096 бит

• Ключевую пару генерируют на срок не менее 10 лет

Файл client.crt необходимо направить в банк, чтобы зарегистрировать его на тестовой среде по адресу acquiring@alfabank.ru

Вместе с файлом client.crt нужно указать:

  1. ИНН, наименование организации, на которую регистрируете сертификат

  2. Тип среды, для которой выпущен сертификат: тестовая или промышленная

  3. Информацию о том, как регистрируете сертификат: первично или повторно взамен истёкшего с alias…

  4. К письму обязательно приложите файл client.crt в архиве без пароля

Пример письма:

• Тема письма: Регистрация сертификата на тестовом стенде СБП C2B

• Тело письма: Просим зарегистрировать сертификат, чтобы направлять запросы на тестовый стенд банка по продукту СБП C2B. Сертификат выпущен впервые / повторно взамен истёкшего с alias… Название организации: ИНН: Сертификат — во вложении.

Письмо на регистрацию сертификата можно направить, если кликнуть на email-адрес acquiring@alfabank.ru. Тогда откроется предзап

После регистрации сертификата на тестовой среде банк передаёт клиенту:

  1. Аlias — имя сертификата, который зарегистрирован на тестовой среде. Оно должно быть указано в headers — key-name при напра

  2. Клиентский сертификат RSA/TLS — он нужен, чтобы поднять MTLS-соединение на тестовой среде

  3. Сертификат удостоверяющего центра c2b-ca-test.crt вместе с промежуточным и удостоверяющим сертификатом root для тестово

  4. Тестовый номер терминала TermNo Аутентификация на промышленной среде

Взаимодействие с платёжным шлюзом Альфа-Банка на промышленной среде происходит через интернет по протоколу HTTPS, при

Чтобы установить MTLS-соединение на промышленной среде, банк выдаёт клиенту ключевую пару RSA/TLS — сертификат и приватн

Внимание

ПШ не обрабатывает запросы с сертификатом MTLS-соединения, по которому истёк срок жизни

Если ПО клиента пытается верифицировать серверный сертификат банка, необходимо добавить в доверенные сертификат удостове

Клиентский самоподписанный сертификат подписывает каждое тело запроса, которое клиент направляет на промышленной среде

Чтобы получить этот сертификат, клиенту необходимо самостоятельно сгенерировать ключевую пару client.crt и client.key:

• client.crt — сертификат, который клиент передаёт в банк, чтобы зарегистрировать на промышленной среде

12/23/25, 11:20 AM Главная

https://alfabank.ru/sme/payservice/sbp/docs/welcome/ 2/7

mailto:admin@test.ru mailto:acquiring@alfabank.ru mailto:acquiring@alfabank.ru

• client.key — приватный ключ, который клиент оставляет у себя, чтобы подписывать тело запроса на промышленной среде

Пример генерации запроса на ключевую пару client.crt и client.key с помощью OpenSSL:

Пример заполнения полей

• Country Name (2 letter code) []: RU

• State or Province Name (full name) []:

• Locality Name (eg, city) []: Moscow

• Organization Name (eg, company) []: COMPANY

• Organizational Unit Name (eg, section) []: IT

• Common Name (eg, fully qualified host name) []: Company Pay C2B

• Email Address []: admin@test.ru

Примечание

• Длина RSA ключа может быть 2048 или 4096 бит

• Ключевую пару генерируют на срок не менее 10 лет

Файл client.crt необходимо направить в банк, чтобы зарегистрировать его на промышленной среде по адресу acquiring@alfabank.ru

Вместе с файлом client.crt необходимо указать:

  1. ИНН, наименование организации, на которую регистрируете сертификат

  2. Тип среды, для которой выпущен сертификат: тестовая или промышленная

  3. Информацию о том, как регистрируете сертификат: первично или повторно взамен истёкшего с alias…

  4. К письму обязательно приложите файл client.crt в архиве без пароля

• Тема письма: Регистрация сертификата на промышленном (боевом) стенде СБП C2B

• Тело письма: Просим зарегистрировать сертификат, чтобы направлять запросы на промышленный (боевой) стенд банка по продукту СБП C2B. Сертификат выпущен впервые / повторно взамен истёкшего с alias… Название организации: ИНН: Сертификат во вложении.

Письмо на регистрацию сертификата можно направить, если кликнуть на email-адрес acquiring@alfabank.ru. Тогда откроется предзап

После регистрации сертификата на промышленной среде банк передаёт клиенту:

  1. Аlias — имя сертификата, который зарегистрирован на промышленной среде. Оно должно быть указано в headers — key-name при

  2. Клиентский сертификат RSA/TLS — он нужен, чтобы поднять MTLS-соединение на промышленной среде

  3. Сертификат удостоверяющего центра c2b-ca.crt вместе с промежуточным и удостоверяющим сертификатом root для промышлен

  4. Эндпойнт промышленной среды

Тестирование

Чтобы провести тестирование, клиент может использовать тестовый стенд.

Эндпойнт тестовой среды (маршрут отправки) — https://217.12.103.132:2443/fsCryptoProxy

Для направления запросов обязательны следующие headers:

openssl req -x509 -newkey rsa:4096 -keyout private.key -out client.crt -nodes -days 3650

12/23/25, 11:20 AM Главная

https://alfabank.ru/sme/payservice/sbp/docs/welcome/ 3/7

mailto:admin@test.ru mailto:acquiring@alfabank.ru mailto:acquiring@alfabank.ru https://217.12.103.132:2443/fsCryptoProxy

• Content-Type — application/x-www-form-urlencoded

• Authorization — помещается hash полученного тела запроса

• key-name — помещается alias зарегистрированного самоподписанного клиентского сертификата

На тестовой среде взаимодействие происходит по протоколу HTTPS.

Пример, как можно направить запрос на тестовом стенде

  1. Составить тестовый запрос.

Порядок параметров в строке для вычисления hash должен соответствовать порядку, в котором параметры передаются в запрос

Пример, как сформировать блок данных:

Обязательно

В блоке данных для подписи сообщения нужно исключить все пробелы, символы табуляции и переноса строки между ключа

Примечание по полю «paymentPurpose»:

• Максимальная длина значения paymentPurpose — 140 символов

• Для значения paymentPurpose можно использовать такие символы:

• Символы латинского алфавита (A–Z и a–z) с десятичными кодами из диапазонов [065–090] и [097–122] в кодировке UTF-8

• Символы русского алфавита (А–Я и а–я) с десятичными кодами из диапазона [1040–1103] в кодировке UTF-8

• Цифры 0–9 с десятичными кодами из диапазона [048–057] в кодировке UTF-8

• Специальные символы с десятичными кодами из диапазонов [032–047], [058–064], [091–096], [123–126] в кодировке UTF-8

• Символ № под номером 8470 в кодировке UTF-8

• Символы ё с кодом 1105 и Ё с кодом 1025 не входят в допустимый диапазон для методов СБП API. Если paymentPurpose исполь

• Нельзя переводить каретку и знак табуляции НСПК допускает символы \ и n, но, чтобы совместно использовать их в JSON, н

• paymentPurpose: Платеж по дог\nовору… — неправильно

• paymentPurpose: Платеж по дог\nовору… — правильно

{

"command":"GetQRCd",

"TermNo":"90080567",

"qrcType":"01",

"amount":"100",

"currency":"RUB",

"paymentPurpose":"Назначение платежа"

}

12/23/25, 11:20 AM Главная

https://alfabank.ru/sme/payservice/sbp/docs/welcome/ 4/7

  1. Из готового запроса необходимо вычислить hash по функции sha256 и зашифровать его приватным ключом тестовой среды

Рассчитать и закрыть hash приватным ключом с помощью такой команды:

Рассмотрим пример с использованием библиотеки OpenSSL:

• client.key — имя файла приватного ключа

• signature.txt — имя файла, в который будет записан зашифрованный hash

• block.txt — имя файла с блоком данных, необходимых, чтобы рассчитать hash

Десериализовать полученные байты в base64 при помощи команды:

• signature64.txt — имя файла, в который будет записан зашифрованный hash по стандарту base64

Готовую строку нужно поместить в заголовок Authorization.

  1. Проверить результат можно так:

Извлечь открытый ключ из сертификата client.crt командой:

• client.crt — имя файла клиентского сертификата

• signing-pub.key — имя файла, который получает открытый ключ

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

• signature.txt — имя файла, в который записан зашифрованный hash

• signing-pub.key — имя файла открытого ключа

• block.txt — имя файла с блоком данных, по которому рассчитан hash

Если проверка прошла успешно, придёт ответ Verified OK.

Примечание

• Команда для проверки кодировки: file -bi block.txt

• Команда для проверки символа новой строки в конце: cat -e block.txt

• Команда для удаления символа новой строки в конце: truncate -s -1 block.txt

Пример поля в составе запроса:

Клиент отправляет запрос с заголовком autorization и сообщением, которое подписано приватным ключом клиента client.key и загол

openssl dgst -sha256 -sign client.key -out signature.txt block.txt

base64 signature.txt > signature64.txt

openssl x509 -in client.crt -pubkey -noout > signing-pub.key

openssl dgst -sha256 -signature signature.txt -verify signing-pub.key block.txt

Content-Type: application/x-www-form-urlencoded

Authorization: QMm5QWnAAj8Tp1hoIvGf1Hv7RPBoGgsDyGiR5GQ2v/MaS7Yaix6LDwAcry0UBWDZzqle2hx2fC7WbWkxXGvxK2Hcx

key-name: c2b-tsp-test

12/23/25, 11:20 AM Главная

https://alfabank.ru/sme/payservice/sbp/docs/welcome/ 5/7

Body:

Как провести тестовую оплату

  1. Откройте на смартфоне ссылку https://testpay.alfabank.ru/sbp-page и нажмите Сканировать QR

  2. Наведите камеру смартфона на QR-код

  3. Нажмите Произвести оплату. Готово: оплата на тестовом контуре выполнена. Переходить в выбор банков не надо.

{"command":"GetQRCd","TermNo":"30000018","qrcType":"01","amount":"100","currency":"RUB","paymentPurpose"

12/23/25, 11:20 AM Главная

https://alfabank.ru/sme/payservice/sbp/docs/welcome/ 6/7

https://testpay.alfabank.ru/sbp-page

Получение статуса платежа по QR-коду, который уже оплачен

Получить статус платежа по QR-коду можно с помощью запроса GetQRCstatus или callback-уведомления от ПШ.

Запрос GetQRCstatus позволяет получить статус по оплаченному динамическому QR-коду, кассовой платёжной ссылке или при опла

Callback-уведомление уходит по оплаченному статическому и динамическому QR-коду, по кассовой платёжной ссылке или при опла

Чтобы получать callback-уведомления, торгово-сервисному предприятию (далее — ТСП) необходимо направить на email acquiring@alf

Сервер на стороне ТСП должен быть публичным, иметь протокол HTTPS и 443 порт.

Адреса, с которых ПШ отправляет callback-уведомления: 217.12.97.124, 217.12.101.32.

Дополнительная информация по вызову метода GetQRCstatus

• В интеграционном тестовом окружении для метода GetQRCstatus введено ограничение частоты запросов: не более 4 запросов в м

• Ограничение введено в связи с лимитами на стороне НСПК (Национальная система платёжных карт): общий лимит — 60 запросов в

• Чтобы исключить паразитический/избыточный трафики обеспечить стабильность работы тестового контура, мы выделили для да

• При превышении лимита запросы будут отвергаться кодом 429 (Too Many Requests).

Переход на промышленную среду

Чтобы перейти на промышленную среду, необходимо заключить сделку по СБП с Альфа-Банком и запросить боевые доступы — для

Пример письма есть в разделе Аутентификация на промышленной среде

Срок, за который банк предоставит боевые данные, — до трёх рабочих дней.

12/23/25, 11:20 AM Главная

https://alfabank.ru/sme/payservice/sbp/docs/welcome/ 7/7

mailto:acquiring@alfabank.ru

View Git Blame Copy Permalink