forked from apoloz/alfa-bank-sdk
431 lines
23 KiB
Markdown
431 lines
23 KiB
Markdown
Главная
|
||
|
||
Добро пожаловать на портал с инструкцией по интеграции СБП 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
|
||
|