Обзор API

• •

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

• •

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

• •

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

• •

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

• •

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

• •

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

• •

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

• •

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

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

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

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

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

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

Файл 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 — сертификат и приватный ключ. Срок жизни сертификата — два года. Когда он истечёт, необходимо заменить ключевую пару на новую — её можно предварительно заказать в банке.

Если ПО клиента пытается верифицировать серверный сертификат банка, необходимо добавить в доверенные сертификат удостоверяющего центра 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

Файл 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.

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

Клиент отправляет запрос с заголовком 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":"Назначение платежа"}

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

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

   

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

   

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

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

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

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

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

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

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

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

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

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

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

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