Обзор API

API позволяет направлять запросы на платежный шлюз Альфа-Банка с целью совершения операций с использованием сервиса СБП C2B.

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

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

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

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

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

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

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

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

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

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

Для установления MTLS соединения на тестовой среде Банк выдаёт клиенту ключевую пару RSA/TLS (сертификат + приватный ключ). Срок жизни сертификата устанавливается Банком на 2 года. По истечении срока жизни сертификата, клиенту необходимо заменить данную ключевую пару на новую, заказав её предварительно в Банке. Поднятие данного соединения позволяет произвести двухстороннюю аутентификацию.

Внимание: запросы, направляемые на ПШ Банка, с сертификатом для поднятия 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 лет (3650 дней)

Полученный файл «client.crt» необходимо направить в Банк для регистрации на тестовой среде по адресу acquiring@alfabank.ru

При направлении файла «client.crt» на регистрацию в Банк, клиент указывает:

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

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

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

4. К письму ОБЯЗАТЕЛЬНО прикладывается файл «client.crt» в архиве без пароля

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

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

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

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

Взаимодействие с платёжным шлюзом Альфа‑Банка на промышленной среде осуществляется через сеть Интернет по протоколу HTTPS с обязательным установлением MTLS соединения.

Для установления MTLS соединения на промышленной среде Банк выдаёт клиенту ключевую пару RSA/TLS (сертификат + приватный ключ). Срок жизни сертификата устанавливается Банком на 2 года. По истечении срока жизни сертификата, клиенту необходимо заменить данную ключевую пару на новую, заказав её предварительно в Банке. Поднятие данного соединения позволяет произвести двухстороннюю аутентификацию.

Внимание: запросы, направляемые на ПШ Банка, с сертификатом для поднятия 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 лет (3650 дней)

Полученный файл «client.crt» необходимо направить в Банк для регистрации на промышленной среде по адресу acquiring@alfabank.ru

При направлении файла «client.crt» на регистрацию в Банк, клиент указывает:

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

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

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

4. К письму ОБЯЗАТЕЛЬНО прикладывается файл «client.crt» в архиве без пароля

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

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

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

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

Для проведения тестирования клиенту доступен тестовый стенд.

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

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

1. Content-Type — «application/x-www-form-urlencoded»;

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

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

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

Пример направления запроса на тестовом стенде.

1. Составить тестовый запрос.
   Порядок параметров в строке для вычисления hash должен соответствовать порядку, в котором параметры передаются в запросе.
   Пример формирования блока данных:

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

   ОБЯЗАТЕЛЬНО: В блоке данных для подписи сообщения, исключить все пробелы, символы табуляции и переноса строки между ключами!
   Примечание по полю «paymentPurpose»:

   1. Максимальная длина значения «paymentPurpose» составляет 140 символов.

   2. Для значения «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 при отправке в НСПК;

   3. Запрещен перевод каретки и знак табуляции. Однако НСПК допускает использование символов «\» и «n», но совместное использование в JSON «\n» требует экранирования:

      • •

        "paymentPurpose": "Платеж по дог\nовору..." – неправильно;

      • •

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

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

   2.1. Команда для расчета hash и закрытия его приватным ключом на примере использования библиотеки OpenSSL:

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

   • •

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

   • •

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

   • •

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

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

   base64 signature.txt > signature64.txt

   • •

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

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

4. Проверить получившийся результат можно следующим образом:

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

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

   • •

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

   • •

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

   4.2. Получив открытый ключ проверить данные с помощью команды:

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

   • •

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

   • •

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

   • •

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

   В случае если проверка прошла успешно, получаем: «Verified OK».

Примечание:

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

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

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

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

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

   

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

   

3. Нажмите на кнопку «Произвести оплату».
   После нажатия этой кнопки, оплата на тестовом контуре будет считаться выполненной.

   

4. ПЕРЕХОДИТЬ В ВЫБОР БАНКОВ НЕ НАДО. ОПЛАТА УЖЕ ВЫПОЛНЕНА!!!

5. При считывании данного QR-кода смартфоном откроется эмулятор оплаты https://pay.alfabank.ru/ecommerce/sbp-page.

   

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

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