Files
alfa-bank-sdk/_docs/alfabank/qr_payout/1_main.md

431 lines
23 KiB
Markdown
Raw Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
Главная
Добро пожаловать на портал с инструкцией по интеграции СБП 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
2. Из готового запроса необходимо вычислить hash по функции sha256 и зашифровать его приватным ключом тестовой среды
Рассчитать и закрыть hash приватным ключом с помощью такой команды:
Рассмотрим пример с использованием библиотеки OpenSSL:
• client.key — имя файла приватного ключа
• signature.txt — имя файла, в который будет записан зашифрованный hash
• block.txt — имя файла с блоком данных, необходимых, чтобы рассчитать hash
Десериализовать полученные байты в base64 при помощи команды:
• signature64.txt — имя файла, в который будет записан зашифрованный hash по стандарту base64
Готовую строку нужно поместить в заголовок Authorization.
3. Проверить результат можно так:
Извлечь открытый ключ из сертификата 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