Главная

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

Здесь есть вся необходимая информация, которая поможет успешно провести прямую интеграцию с платёжным шлюзом Альфа‑Банка по проекту СБП C2B: описание методов API, параметры запросов и ответов и полезные советы по настройке.

Важное объявление
С 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 соединения на тестовой среде, вам необходимо обратиться в банк по адресу acquiring@alfabank.ru за её получением
Информация о том, как направлять запросы с установлением MTLS соединения на тестовой среде, находится по ссылке в разделе «Аутентификация на тестовой среде»

Обзор API

  • •

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

  • •

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

  • •

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

  • •

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

  • •

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

  • •

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

  • •

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

  • •

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

  • •

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

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

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

Взаимодействие с платёжным шлюзом Альфа‑Банка (далее — ПШ) на тестовой среде происходит через интернет по протоколу HTTPS, при этом обязательно нужно установить MTLS-соединение.

Чтобы установить MTLS-соединение на тестовой среде, банк выдаёт клиенту ключевую пару RSA/TLS: сертификат и приватный ключ. Срок жизни сертификата — два года. Когда он истечёт, необходимо заменить ключевую пару на новую — её можно предварительно заказать в банке.

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

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

Если ПО клиента пытается верифицировать серверный сертификат банка, необходимо добавить в доверенные сертификат удостоверяющего центра — c2b-ca-test.crt, который также выдаёт банк.

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

Чтобы получить этот сертификат, необходимо самостоятельно сгенерировать ключевую пару 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

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

  • •

    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-соединение.

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

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

Если ПО клиента пытается верифицировать серверный сертификат банка, необходимо добавить в доверенные сертификат удостоверяющего центра c2b-ca.crt, который также выдаёт банк.

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

Чтобы получить этот сертификат, клиенту необходимо самостоятельно сгенерировать ключевую пару 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

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

  • •

    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:

  • •

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

  • •

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

  • •

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

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

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

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

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

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

    {  
"command":"GetQRCd",  
"TermNo":"90080567",  
"qrcType":"01",  
"amount":"100",  
"currency":"RUB",  
"paymentPurpose":"Назначение платежа"  
}

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

    Примечание по полю «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 использует их, чтобы создать QR, то заменяет на e/E и отправляет в НСПК в таком виде

    • •

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

      • •

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

      • •

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

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

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

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

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

    • •

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

    • •

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

    • •

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

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

    base64 signature.txt > signature64.txt
    • •

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

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

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

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

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

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

    • •

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

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

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

      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 и заголовком key-name.

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

Authorization: QMm5QWnAAj8Tp1hoIvGf1Hv7RPBoGgsDyGiR5GQ2v/MaS7Yaix6LDwAcry0UBWDZzqle2hx2fC7WbWkxXGvxK2HcxUQqCBPXaHK5Zk6HMeU/dREi22kQtHuv5g1bBPNhQiYBzUaTSjeC8Y8dqJnpc8//G6UkB7Ki4RqGE65g3sDqdEpVf3jgs8IV429yCYd4qHx5YxAF4QgtzCXRZT0gAQfLZohtuDWMsTOf1qu9t+/BqLuz/kQk3onL/oED1z4/C2n24ICgTnvNSUA0td0A9dPSah6sNKQp4AgBCw3sqdLIKFu1biA6lUE4O49u1w8lfNJAN+NmD39641oYFM3p9A==

key-name: c2b-tsp-test

Body:

{"command":"GetQRCd","TermNo":"30000018","qrcType":"01","amount":"100","currency":"RUB","paymentPurpose":"Назначение платежа"}

Оплата на тестовом стенде по QR-коду

Оплата с помощью тестового WEB-приложения

Альфа‑Банк предоставляет WEB-приложение для проведения тестовых платежей от имени покупателя.

Приложение можно открыть в браузере любого устройства, имеющего камеру.

После открытия приложения необходимо нажать на кнопку Сканировать QR (при необходимости разрешить браузеру доступ к камере) и отсканировать изображение тестового QR-кода.

Для того чтобы совершить неуспешную транзакцию, необходимо сгенерировать QR-код на сумму 50000311 и отсканировать его с помощью WEB-приложения.

Приложения банков не работает для оплаты QR-кодов в тестовой среде.

Ниже приведена пошаговая инструкция:

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

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

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

Оплата с помощью методов REST API

Метод REST API — TestPayQR

Метод позволяет совершить оплату по QR-коду на тестовом стенде.

Оплата может быть как успешной — ACWP, так и неуспешной — RJCT.

Для получения идентификатора qrcId, необходимо направить запрос GetQRCd.

При генерации QR-кода в поле сумма всегда задавать значение — 100 руб. (10000 в минорных единицах).

Статус платежа можно получить в нотификации (предварительно настроив получение callback-уведомлений) или направив запрос GetQRCstatus.

Описание параметров запроса:

Код ключаТип данныхrequiredОписание
commandstring+Тип запроса. Константа TestPayQR
qrcIdstring+Идентификатор QR-кода
TermNostring+Уникальный идентификатор терминала
queryData.notificationUrlstring-Полный URL для получения уведомления о финальном статусе оплаты QR-кода
Statusstring+

Варианты эмуляции статуса операции:

— ACWP — ACCEPTED операция завершена успешно;

— RJCT — REJECTED операция отклонена.

Примерный формат запроса для оплаты ACWP:

{
  "command":" TestPayQR ",
  "TermNo":"90080567 ",
  "qrcId": "AD100026KQ0ESJBV8OFPCG0U9K1H52UM", 
  "status": " ACWP "
  "queryData":
      {
          "notificationUrl":"https://sbp-payments",
      }
}

Примерный формат ответа для оплаты ACWP:

{
  "ErrorCode": 0,
  "message": "Запрос TestPayQR выполнен успешно",
  "Status": "ACWP"
}

Примерный формат запроса для оплаты RJCT:

{
  "command":" TestPayQR ",
  "TermNo":"90080567 ",
  "qrcId": "AD100026KQ0ESJBV8OFPCG0U9K1H52UM", 
  "status": " RJCT "
  "queryData":
      {
          "notificationUrl":"https://sbp-payments",
      }
}

Примерный формат ответа для оплаты RJCT:

{
  "ErrorCode": 0,
  "message": "Запрос TestPayQR выполнен успешно",
  "Status": "RJCT "
}

Моделирование отказов при оплате с привязанного счёта на тестовом стенде

Чтобы получить отказ в оплате с привязанного счёта, необходимо в запросе QRCSubPayPetition в поле subscriptionToken поместить один из нижеуказанных идентификаторов:

  • •

    8521f00a41734046ac5cd46282c230b8 — RQ05032 Отказ Банка Плательщика в проведении платежа

  • •

    8521f00a41734046ac5cd46282c230d9 — RQ05060 Недостаточно денежных средств для проведения операции

  • •

    8521f00a41734046ac5cd46282c230c3 — RQ05061 Превышен лимит по сумме операций по СБП

  • •

    8521f00a41734046ac5cd46282c230a2 — RQ05062 Превышен лимит по количеству операций по СБП

  • •

    8521f00a41734046ac5cd46282c230o7 — RQ05063 Подозрение в мошенничестве

  • •

    8521f00a41734046ac5cd46282c230j6 — RQ05064 Выполнение операций в данной категории ТСП запрещено

  • •

    8521f00a41734046ac5cd46282c230z1 — RQ05065 Счёт заблокирован

  • •

    8521f00a41734046ac5cd46282c230f4 — RQ05066 Счёт закрыт

  • •

    8521f00a41734046ac5cd46282c230k5 — RQ05067 Выполнение операции запрещено по требованию законодательства

Данные идентификаторы соответствуют определенным кодам ошибок, которые возвращает Банк плательщика при отказе в совершении оплаты с привязанного счёта. Коды возвращаются в callback уведомлении по методу resolution /notification.

При этом значение qrcid для запроса QRCSubPayPetition формируется стандартным способом с использованием метода GetQRCd.

Оплата на тестовом стенде по Цифровому рублю (ЦР)

Данный метод предназначен для проведения тестирования оплат по Цифровому рублю.

По факту генерации QR-кода с ЦР, чтобы получить успешный статус по оплате и нотификацию нужно направить соответствующий запрос на адрес https://217.12.103.132:9443/api/v3/organisation/callback/OrganisationC2BNotification, указав в запросе идентификатор вашего QR-кода (reference), сумму (transferAmount) и, по необходимости, идентификатор кассовой ссылки (paramsId).

HEADERS
Content-Typeapplication/json
AuthorizationBasic UHJlaG9zdEMyQi8xMTE=

Описание параметров запроса:

Код ключаТип данныхrequiredОписание
operationIdstring+Идентификатор операции на ПлЦР
participantIdstring+Идентификатор Клиента-ЮЛ на ПлЦР
participantWalletIdstring+Идентификатор кошелька Клиента-ЮЛ на ПлЦР
organisationIdstring+Идентификатор Клиента-ЮЛ в Банке
referencestring+Идентификатор QR-кода (НСПК)
transferAmountnumber+Сумма перевода, в том виде, в котором поступает от ПлЦР — рубли с копейками с разделителем точка
merchantNamestring+Наименование ТСП
purposestring+Назначение платежа
settlementDateTimestring+Дата и время исполнения платежа
innstring+ИНН организации
paramsidstring+Идентификатор активных значений параметров кассовой ссылки
paymentLinkIdstring+Идентификатор QR-кода (НСПК)

Примерный формат запроса:

1{
2    "operationId": "123456ggg789",
3    "participantId": "55464QQZZ13131313",
4    "participantWalletId": "g.ru.cbrdc.wlt.clt.ffeb94e1-5e89-45c7-97a8-60352ff2b5a9",
5    "organisationId": "UDC8K8",
6    "inn": "7014065307",
7    "paramsid": "",
8    "reference": "AD20101IQSS3NVAN8068HO2NAGPQJG64",
9    "transferAmount": "4.00",
10    "merchantName": "ГАЗМЯС",
11    "paymentLinkId": "AD20101IQSS3NVAN8068HO2NAGPQJG64",
12    "purpose": "FHDUv8vYPUhWSy",
13    "settlementDateTime": "2026-07-24T12:52:23.000Z"
14}

Важно:

  1. Изменение следующих параметров запроса без согласования Банка не допускается:

    • •

      participantId

    • •

      participantWalletId

    • •

      organisationId

    • •

      merchantName

    • •

      inn

  2. Обращаем ваше внимание, что ответ на данный метод не поступает. Вы можете убедиться в корректности проведения платежа следующими способами:

    • •

      направив запрос статуса платежа методом REST API — GetQRCstatus (ендпойнт https://217.12.103.132:2443/fsCryptoProxy)

    • •

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

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

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

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

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

Чтобы получать callback‑уведомления, торгово‑сервисному предприятию (далее — ТСП) необходимо направить на email acquiring@alfabank.ru доменное имя сервера ТСП. Банк зарегистрирует его. На это имя будут приходить уведомления.

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

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

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

  • •

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

  • •

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

  • •

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

  • •

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

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

Чтобы перейти на промышленную среду, необходимо заключить сделку по СБП с Альфа‑Банком и запросить боевые доступы — для этого направить запрос по email‑адресу acquiring@alfabank.ru

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

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

Платёжная страница

Если вы планируете использовать персональную платёжную страницу, вам необходимо реализовать виджет выбора банков.

Спецификация API виджета банков размещена по ссылке https://widget.cbrpay.ru.