Files
alfa-bank-sdk/_docs/alfabank/qr_payout/0_full.md

70 KiB
Raw Blame History

Главная

Инструкция по интеграции СБП C2B (Альфа-Банк)

Добро пожаловать в руководство по прямой интеграции с платежным шлюзом (ПШ) Альфа-Банка для реализации сервиса СБП C2B.


⚠️ Важное объявление (Изменение адресов)

С 01.11.2024 адрес тестового стенда изменен. Старые адреса недоступны.

  • Новый URL тестового стенда: https://217.12.103.132:2443/fsCryptoProxy
  • Условие доступа: Обязательное установление MTLS соединения.

1. Обзор API

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

Параметр Описание
Протокол HTTPS
Архитектура REST
Методы POST
Формат данных JSON (аргументы и ответы)
Кодировка текста urlencoded (внутри JSON ответов)
Поддержка acquiring@alfabank.ru

Особенности обработки ошибок

  • Каждый ответ содержит поле ErrorCode.
  • При возникновении логической ошибки описание возвращается в поле message.

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

Для работы со шлюзом (и на тестовой, и на промышленной среде) используется двусторонняя аутентификация MTLS и подпись тела запроса.

2.1. Генерация сертификатов (Self-signed)

Клиент должен самостоятельно сгенерировать ключевую пару RSA для подписи запросов.

Команда OpenSSL:

openssl req -x509 -newkey rsa:4096 -keyout private.key -out client.crt -nodes -days 3650

Рекомендуемые параметры заполнения:

  • Country (RU), City (Moscow), Organization (Ваша компания).
  • Common Name: Company Pay C2B.
  • Срок действия: не менее 10 лет.
  • Длина ключа: 2048 или 4096 бит.

2.2. Регистрация в банке

Файл client.crt необходимо отправить на acquiring@alfabank.ru.

Шаблон письма:

Тема: Регистрация сертификата на [тестовом/промышленном] стенде СБП C2B

Тело: Просим зарегистрировать сертификат для работы с СБП C2B.

  • Тип регистрации: Впервые / Повторно (взамен истёкшего alias...)
  • Организация: [Название]
  • ИНН: [Номер]
  • Вложение: client.crt (в архиве без пароля)

2.3. Что вы получите от банка

После регистрации банк предоставит:

  1. Alias — имя вашего сертификата (передается в заголовке key-name).
  2. Клиентский сертификат RSA/TLS — для поднятия MTLS-соединения.
  3. Корневые сертификаты банка — для проверки серверного сертификата.
  4. TermNo — тестовый номер терминала.
  5. Эндпойнт — для промышленной среды.

3. Техническая реализация запроса

3.1. Формирование заголовков (Headers)

При каждом запросе необходимо передавать следующие заголовки:

Заголовок Значение
Content-Type application/x-www-form-urlencoded
Authorization Base64-строка зашифрованного хеша (см. ниже)
key-name Ваш Alias, полученный от банка

3.2. Подпись сообщения (Security)

Процесс формирования заголовка Authorization:

  1. Подготовка данных: Сформируйте JSON-тело запроса. Исключите все пробелы, табуляции и переносы строк между ключами и значениями.
  2. Вычисление хеша и подпись:
    # Расчет SHA256 и подпись приватным ключом
    openssl dgst -sha256 -sign client.key -out signature.txt block.txt
    
  3. Кодирование в Base64:
    # Получение строки для заголовка Authorization
    base64 signature.txt > signature64.txt
    

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

4.1. Эндпойнт тестовой среды

https://217.12.103.132:2443/fsCryptoProxy

4.2. Пример запроса (GetQRCd)

Body:

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

Важно по полю paymentPurpose:

  • Макс. длина: 140 символов.
  • Допустимы: Латиница, Кириллица (кроме Ё/ё), цифры и спецсимволы.
  • Перенос строки передается как \\n (двойной слэш для JSON).

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

  1. Сгенерируйте QR-код через API.
  2. Откройте на смартфоне: testpay.alfabank.ru/sbp-page.
  3. Нажмите "Сканировать QR" и наведите камеру на код.
  4. Нажмите "Произвести оплату". Выбор банка не требуется.

5. Статусы и уведомления

Получение статуса платежа

Существует два способа:

  1. Запрос GetQRCstatus: Опрос шлюза клиентом.
  2. Callback-уведомления: ПШ банка отправляет POST-запрос на ваш сервер.

Настройка Callback

  • Сервер ТСП должен быть публичным (HTTPS, порт 443).
  • IP-адреса банка для белого списка: 217.12.97.124, 217.12.101.32.
  • Для включения отправьте URL обработчика на acquiring@alfabank.ru.

Лимиты на тестовой среде (GetQRCstatus)

  • Лимит ТСП: не более 4 запросов в минуту.
  • Общий лимит НСПК: 60 запросов в минуту на весь банк.
  • При превышении возвращается ошибка 429 Too Many Requests.

6. Переход в промышленную среду (Production)

Для выхода в "бой" необходимо:

  1. Заключить договор по СБП с Альфа-Банком.
  2. Сгенерировать новую ключевую пару для промышленной среды.
  3. Направить письмо на регистрацию (аналогично тестовой, но с пометкой "промышленный стенд").
  4. Срок предоставления доступов — до 3 рабочих дней.

Общие положения

Техническая документация СБП: Общие положения

Данный документ описывает принципы взаимодействия, идентификации и основные бизнес-сценарии при работе с Системой Быстрых Платежей (СБП) через хост Альфа-Банка.


1. Каналы взаимодействия и безопасность

Взаимодействие осуществляется по протоколу HTTP(S) с обязательной двусторонней аутентификацией.

Требования к сертификатам

  • Тип: Клиентские сертификаты RSA/TLS.
  • Управление: Порядок выпуска и установки определяется Удостоверяющим Центром Заказчика.
  • Именование (Alias): На прокси-сервере Заказчика должны соблюдаться строгие правила именования:
Параметр Требование к имени (алиасу)
Обычный запрос Должно соответствовать коду терминала и реквизиту заголовка key-name.
Проверка соединения Должно быть равно параметру TermNo в теле запроса и заголовку key-name.

2. Идентификация Виртуального терминала

Для работы в системе каждому терминалу присваивается уникальный идентификатор — TermNo.

  • Назначение: Определение конкретного виртуального терминала, кассы или системы.
  • Привязка: TermNo определяет принадлежность к Юридическому лицу (ЮЛ), конкретной точке продаж (ТСП) и расчетному счету, на который будут поступать средства.
  • Лимиты: Минимум 1 терминал на адрес ТСП, максимум — по запросу.
  • Применение:
    • Сохраняется в настройках терминала.
    • Используется на прикладном уровне протокола совместно с сертификатом.
    • Обязателен для генерации динамических QR-кодов и проверки статуса оплаты.

3. Общий порядок работы

3.1. Оплата покупки (C2B)

Процесс проведения оплаты через динамический QR-код:

  1. Инициация: Кассир вводит сумму (валюта и назначение платежа обычно подставляются автоматически).
  2. Запрос QR: ТСП запрашивает динамический QR-код у Банка.
  3. Отображение: ТСП выводит QR на экран или печатает пре-чек.
  4. Действия клиента:
    • Сканирует QR через банковское приложение.
    • Подтверждает оплату.
  5. Проверка: ТСП запрашивает подтверждение статуса платежа.
  6. Фискализация: При получении статуса «Оплачено» ТСП печатает чек.

Обязательные реквизиты в чеке оплаты:

  • qrcId (Идентификатор QR-кода)
  • Код транзакции СБП
  • Дата и время операции

3.2. Возврат покупки

Возврат средств имеет ряд технологических особенностей.

Important

Ограничения возврата:

  • Возможен только при наличии чека и кода транзакции СБП.
  • Осуществляется только по номеру телефона плательщика.
  • Средства возвращаются только в тот же Банк-участник СБП, с которого была оплата.

Параметры для инициации возврата:

  • Сумма (полная или частичная) и валюта.
  • Данные из чека: qrcId, Код транзакции, Дата оплаты.

Процесс подтверждения:

  1. Хост Банка проверяет наличие исходной операции.
  2. Кассир проходит аутентификацию (ввод одноразового кода SMS/Push или иная проверка полномочий).
  3. ТСП отправляет финальный запрос на возврат.

Реквизиты в чеке возврата:

  • Код транзакции payrrn
  • Сумма возврата

4. Работа с кассовыми ссылками

Кассовая ссылка — это многоразовый QR-код, который активируется под конкретную покупку.

Жизненный цикл ссылки

  1. Регистрация: ТСП через Агента регистрирует ссылку в ОПКЦ СБП. QR-код размещается в кассовой зоне.
  2. Активация: В момент покупки ТСП отправляет запрос на активацию ссылки, передавая сумму, валюту и назначение платежа.
    • Совет: Для получения уведомлений передавайте адрес callback-url.
  3. Оплата: Клиент считывает статическую ссылку, которая после активации ведет на оплату конкретного счета.
  4. Деактивация: Если оплата не состоялась, ТСП отправляет запрос на деактивацию.
  5. Изменение счета: ТСП может изменить расчетный счет, привязанный к ссылке, через запрос к Агенту ТСП (автоматические уведомления об изменении не поддерживаются).

5. Привязка счета и рекуррентные платежи

Сценарии для реализации оплат «в один клик» или подписок.

Сценарии регистрации привязки

Тип сценария Описание
Чистая привязка Регистрация QR-кода типа 03. Клиент сканирует код только для привязки счета без оплаты.
Оплата + Привязка При регистрации обычного QR на оплату передается параметр subscriptionPurpose. После оплаты банк предлагает клиенту привязать счет.

Оплата по инициативе ТСП (Списание без участия клиента)

  1. ТСП регистрирует QR для оплаты с привязанного счета.
  2. ТСП направляет запрос на оплату в НСПК.
  3. НСПК запрашивает подтверждение у Банка Плательщика.
  4. При положительном ответе инициируется C2B операция, и Агент ТСП получает уведомление о финальном статусе.

Справочник параметров (Сниппеты данных)

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

// Пример ключевых полей для активации кассовой ссылки / оплаты
{
  "TermNo": "12345678",        // Номер терминала
  "amount": 10000,             // Сумма в копейках/единицах
  "currency": "RUB",           // Валюта
  "qrcId": "AD100000...",      // ID QR-кода
  "payrrn": "3021...",         // Код транзакции (для возвратов)
  "callbackUrl": "https://..." // Адрес для уведомлений
}

Статический QR-код (СБП)

Статический QR-код — это инструмент безналичной оплаты через Систему быстрых платежей (СБП), являющийся альтернативой эквайрингу. Изображение QR-кода остается неизменным, его можно распечатать и разместить в кассовой зоне.

Особенности

  • Варианты реализации:
    • С открытой суммой (вводит покупатель).
    • С фиксированной суммой (задает продавец при генерации).
  • Способы оплаты: Сканирование камерой смартфона или использование NFC-метки.
  • Скорость: Средства поступают на счет продавца мгновенно.
  • Оборудование: Терминал не требуется.

1. Регистрация статического QR-кода

Метод GetQRCd используется для формирования платежной ссылки и получения изображения QR-кода.

Параметры запроса

Параметр Тип данных Обяз. Назначение
command String Y Константа GetQRCd.
TermNo String(20) Y Уникальный идентификатор терминала.
qrcType String(2) Y Тип QR-кода. Для статического — 01.
amount Number O Сумма в копейках. Если не указана — сумма открытая.
currency String(3) O Код валюты (например, RUB).
paymentPurpose String(140) O Назначение платежа.
width / height String O Размеры изображения QR-кода в пикселях.
redirectUrl String(1024) O Ссылка для возврата клиента в приложение/на сайт ТСП.
messageID String(1024) O Уникальный ID сообщения (GUID). Только латиница.
queryData.notificationUrl String(512) O URL для получения уведомления о статусе оплаты.

Пример запроса

{
  "command": "GetQRCd",
  "TermNo": "90080567",
  "qrcType": "01",
  "width": "600",
  "height": "600",
  "amount": 10000,
  "currency": "RUB",
  "paymentPurpose": "Оплата заказа №123",
  "messageID": "550e8400-e29b-41d4-a716-446655440000",
  "queryData": {
    "notificationUrl": "https://yourserver.com/sbp/notify"
  },
  "redirectUrl": "https://yourshop.ru/success"
}

Параметры ответа

Параметр Тип данных Назначение
ErrorCode String Код ответа (0 — успех).
image String Изображение QR-кода в формате BASE64.
payload String Платежная ссылка (содержимое QR-кода).
qrcId String Уникальный идентификатор QR-кода.
status String Статус регистрации ссылки (например, CREATED).

2. Нотификация о статусе оплаты

После успешной оплаты Банк отправляет POST-запрос на notificationUrl, указанный при регистрации.

Параметры уведомления

Параметр Тип данных Назначение
qrcId String Идентификатор QR-кода.
trxId String Уникальный ID платежа в НСПК.
status String ACWP — успех, RJCT — отклонено.
amount Number Сумма платежа в копейках.
timestamp String Время операции по Гринвичу (GMT).
payerId String Маскированный номер телефона плательщика.

Пример уведомления

{
  "command": "qrc/notification",
  "qrcId": "AS10000NJTDV88TN82CRT8CG1AU690OF",
  "trxId": "A31040920067662400000550448AD7B3",
  "status": "ACWP",
  "amount": 10000,
  "timestamp": "2023-04-14T09:20:06.000Z",
  "payrrn": "000051992395",
  "TermNo": "90080567"
}

ТСП должно ответить HTTP-кодом 200 OK.


3. Проведение возврата

Возврат средств выполняется в два этапа.

3.1. Проверка возможности возврата (GetQRCreversalData)

Используется для получения данных о плательщике и проверки доступности операции.

Запрос:

Параметр Обяз. Описание
qrcId Y ID QR-кода из оригинального платежа.
trxId Y ID транзакции НСПК.
amount O Сумма возврата. Если пусто — полный возврат.

Пример ответа:

{
  "ErrorCode": 0,
  "payerBnkName": "Альфа-Банк",
  "payerId": "*1779",
  "trxDT": "20230414062006",
  "message": "OK"
}

3.2. Выполнение возврата (QRCreversal)

Непосредственная инициация перевода средств клиенту.

Запрос:

Параметр Обяз. Описание
messageID Y GUID, полученный в ответе GetQRCreversalData.
queryData.notificationUrl O URL для уведомления о статусе возврата.

4. Запрос статуса возврата

Метод GetQRCreversalStatus используется для уточнения финального статуса операции возврата (B2C).

Параметры запроса

Для поиска операции необходимо передать одну из пар:

  1. payrrn ИЛИ originalTrxId (для поиска исходного платежа).
  2. trxId ИЛИ messageID (для идентификации самого возврата).

Статусы возврата в ответе

  • ACWP — Возврат успешно завершен.
  • RJCT — Операция отклонена.
  • NTST — Статус неизвестен (в обработке).

Пример ответа

{
  "ErrorCode": 0,
  "amount": 10000,
  "status": "ACWP",
  "originalTrxId": "A31040920067662400000550448AD7B3",
  "trxId": "B31071502287201D00001650448AD7B3"
}

Примечание: Все текстовые данные в запросах должны передаваться в кодировке UTF-8, формат передачи данных — JSON.

Интеграция динамических QR-кодов (СБП)

Оплата по динамическому QR-коду — это способ безналичной оплаты через Систему Быстрых Платежей (СБП). QR-код создается отдельно под каждую покупку, содержит сумму и реквизиты. Средства мгновенно поступают на счёт продавца.

1. Регистрация динамического QR-кода

Метод: GetQRCd

Используется для генерации QR-кода под конкретный заказ.

Параметры запроса

Код ключа Тип данных Обяз. Назначение
command String Y Константа GetQRCd
TermNo String(20) Y Уникальный идентификатор терминала
qrcType String(2) Y Тип QR-кода. Для динамического — 02
amount Number Y Сумма в минорных единицах (копейках)
currency String(3) Y Код валюты (для рублей — RUB)
OrderNumber String(1000) O Номер заказа (только латиница и цифры)
paymentPurpose String(140) O Назначение платежа
qrTtl String(6) O Срок жизни ссылки в минутах (мин. 1, рек. от 5)
queryData.notificationUrl String(512) O URL для уведомления о статусе оплаты
redirectUrl String(1024) O Ссылка для возврата клиента в приложение/сайт
extJsonParams Object O Блок дополнительных параметров (JsonParam1-10)

Для подписок (рекуррентных платежей):

  • subscriptionServiceId: Идентификатор привязки.
  • subscriptionServiceName: Наименование привязки.

Пример запроса

{
  "command": "GetQRCd",
  "TermNo": "90080567",
  "amount": "10000",
  "currency": "RUB",
  "qrcType": "02",
  "qrTtl": "5",
  "OrderNumber": "FYI123456",
  "queryData": {
    "notificationUrl": "https://sbp-payments.your-site.com/callback"
  }
}

Параметры ответа

Код ключа Тип данных Обяз. Назначение
ErrorCode String Y Код ответа (0 — успех)
image String Y Изображение QR-кода в формате Base64
payload String Y Платежная ссылка СБП
qrcId String Y Уникальный идентификатор QR-кода
status String Y Статус регистрации (например, CREATED)

2. Запрос статуса оплаты

Метод: GetQRCstatus

Направляется кассой/терминалом для проверки факта оплаты.

Важно: Запрос следует направлять не ранее, чем через 10 секунд после формирования QR, и не чаще чем раз в 3 секунды.

Параметры запроса

Код ключа Тип данных Обяз. Назначение
command String Y Константа GetQRCstatus
TermNo String Y Идентификатор терминала
qrcId String Y/O ID QR-кода (обязательно, если нет payrrn)
payrrn String Y/O Референс запроса в системе Банка

Возможные статусы (status)

  1. ACWP (ACCEPTED) — Операция завершена успешно.
  2. RJCT (REJECTED) — Операция отклонена.
  3. NTST (NOT_STARTED) — Операция не найдена (нужен повтор запроса).
  4. RCVD (RECEIVED) — Операция в обработке.

Пример ответа (Успех)

{
  "ErrorCode": 0,
  "status": "ACWP",
  "qrcId": "AD100026KQ0ESJBV8OFPCG0U9K1H52UM",
  "trxId": "A3013090427361010000057B3DA2D4A7",
  "amount": 10000,
  "payerId": "*********1234"
}

3. Нотификация о финальном статусе

Метод: qrc/notification

Запрос отправляется со стороны Банка на notificationUrl ТСП.

Формат уведомления

{
  "command": "qrc/notification",
  "qrcId": "AD100026KQ0ESJBV8OFPCG0U9K1H52UM",
  "status": "ACWP",
  "amount": "10000",
  "trxId": "A3013090427361010000057B3DA2D4A7",
  "timestamp": "2022-10-27T14:33:49.000Z"
}

ТСП должно ответить HTTP-кодом 200.


4. Проведение возврата

Возврат может быть выполнен в два этапа (проверка + выполнение) или в один этап (при передаче messageID).

4.1 Проверка возможности возврата (GetQRCreversalData)

Используется для получения данных о плательщике и проверки доступного остатка.

4.2 Выполнение возврата (QRCreversal)

Параметры запроса:

Код ключа Тип данных Обяз. Назначение
command String Y Константа QRCreversal
amount Number O Сумма возврата (если не указана — полный возврат)
qrcId/trxId String Y Идентификаторы оригинальной операции
ReturnRestAmount Boolean O Вернуть остаток доступных средств в ответе

Пример ответа на возврат

{
  "ErrorCode": 0,
  "message": "Возврат проведен",
  "amount": 10000,
  "trxId": "A3024113609260070000086B8426B817",
  "restAmount": "99.87"
}

5. История и статусы возвратов

Запрос истории (GetQRCreversalHistory)

Позволяет получить список всех попыток возврата по одной транзакции оплаты.

Пример структуры массива refunds в ответе:

"refunds": [
  {
    "status": "ACWP",
    "amount": 10000,
    "trxId": "B51390823097450W0000180011510503",
    "trxDT": "20250519082345"
  },
  {
    "status": "RJCT",
    "amount": 10000,
    "trxId": "A4327120041167130000020011381101"
  }
]

6. Нотификация о возврате

Метод: b2c-refund/notification

Банк уведомляет систему ТСП о финальном статусе операции возврата.

Пример уведомления

{
  "command": "b2c-refund/notification",
  "status": "ACWP",
  "amount": "10000",
  "originalTrxId": "X1A2S3D5F6G7H8J9K0C4S5C6D7V5D1K2",
  "trxId": "A3024113609260070000086B8426B817"
}

Примечания

  • Формат данных: Все текстовые данные в ответах передаются в формате urlencoded.
  • Суммы: Все суммы в запросах передаются как целые числа в копейках.
  • Ошибки: Список кодов ошибок приведен в Приложении №2 (согласно основной документации Банка).
  • Успешная оплата: Считается подтвержденной только при получении статуса ACWP и наличии trxId.

Кассовая платёжная ссылка СБП: Техническая документация

Кассовая платёжная ссылка — это гибридное решение, объединяющее преимущества статического и динамического QR-кодов. QR-код остается неизменным (его можно распечатать один раз), но сумма оплаты передается с кассы в момент покупки, что исключает ошибки ручного ввода со стороны клиента.

Общие положения

  • Для каждой кассы/терминала создается уникальная ссылка.
  • Сумма передается в минорных единицах (копейках).
  • Текстовые данные в ответах передаются в формате urlencoded.

1. Регистрация кассовой платёжной ссылки

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

Параметры запроса

Параметр Тип Обяз. Назначение
command String Y Константа RegCashQRc
TermNo String Y Уникальный ID терминала (до 20 симв.)
mediaType String N Тип картинки (напр., image/png)
width String N Ширина изображения
height String N Высота изображения
redirectUrl String N Ссылка для возврата клиента в приложение ТСП
qrcId String N ID для привязки предвыпущенных NFC-табличек

Пример запроса:

{
    "command": "RegCashQRc",
    "TermNo": "90080567",
    "mediaType": "image/png",
    "width": "600",
    "height": "600",
    "redirectUrl": "https://exampletsp.io/callback"
}

2. Активация ссылки (Передача суммы)

Метод ActivateCashQRc вызывается кассой в момент совершения покупки для установки суммы и параметров платежа.

Параметры запроса

Параметр Тип Обяз. Назначение
command String Y Константа ActivateCashQRc
TermNo String Y ID терминала
qrcId String Y ID QR-кода
amount Number Y Сумма в копейках
currency String N Валюта (по умолчанию RUB)
qrTtl String N Срок жизни активации (5–20 мин)
queryData.notificationUrl String N URL для уведомления об оплате

Пример запроса:

{
    "command": "ActivateCashQRc",
    "TermNo": "90080567",
    "qrcId": "BS1R001P1UIGJCFJ9RDQ8974M1I4CJO9",
    "amount": 10000,
    "currency": "RUB",
    "qrTtl": "5",
    "queryData": {
        "notificationUrl": "https://sbp-payments.your-site.ru"
    }
}

3. Проверка статуса оплаты

Метод GetQRCstatus используется для получения финального статуса транзакции. Рекомендуется запрашивать не ранее 10 сек. после активации и не чаще раза в 3 сек.

Статусы оплаты (поле status)

  • ACWP (ACCEPTED) — Оплата успешно завершена.
  • RJCT (REJECTED) — Операция отклонена.
  • NTST (NOT_STARTED) — Оплата еще не инициирована.
  • RCVD (RECEIVED) — В обработке.

Пример ответа (Успех):

{
    "ErrorCode": 0,
    "status": "ACWP",
    "trxId": "A30180803159571F0000097B3DA2D4A7",
    "amount": 10000,
    "payerId": "*********1234",
    "payrrn": "000056251465"
}

4. Деактивация ссылки

Метод DelCashQRc используется для досрочной отмены ожидания оплаты (например, если клиент отказался от покупки).

Пример запроса:

{
    "command": "DelCashQRc",
    "TermNo": "90080567",
    "qrcId": "BS1R001P1UIGJCFJ9RDQ8974M1I4CJO9"
}

5. Возврат платежа

Возврат по СБП выполняется в два этапа (или в один при наличии messageID).

Этап 1: Проверка возможности возврата (GetQRCreversalData)

Позволяет узнать доступный остаток и получить данные для проведения возврата.

Этап 2: Проведение возврата (QRCreversal)

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

{
    "command": "QRCreversal",
    "TermNo": "90080567",
    "payrrn": "000056251465",
    "amount": 10000,
    "messageID": "f9aa54ff-a615-44b8-aa6c-acab655c89f8"
}

6. Нотификации (Webhooks)

Банк отправляет POST-запросы на ваш notificationUrl при изменении статуса оплаты или возврата.

Уведомление об оплате (qrc/notification)

{
    "command": "qrc/notification",
    "qrcId": "BS1R001P1UIGJCFJ9RDQ8974M1I4CJO9",
    "status": "ACWP",
    "amount": 10000,
    "trxId": "A30180803159571F0000097B3DA2D4A7"
}

7. Изменение параметров ссылки

Метод ChangeAccForCashQRc позволяет перепривязать QR-код к другому счету, терминалу или изменить redirectUrl.

Параметр Назначение
NewTermNo Перенос на новый ID терминала
NewMerchantId Перенос на другую торговую точку
account Смена расчетного счета

Приложение: Коды ошибок (ErrorCode)

Код Описание
0 Успешно
3 Не передан обязательный параметр
16 Некорректный TermNo
41 Некорректный qrcId
301 Превышен временной диапазон поиска
RQ05019 Не передан параметр amount при активации

Примечание: При получении статуса NTST необходимо продолжать опрос статуса до получения финального результата (ACWP или RJCT).

Привязка счёта и подписки СБП: Техническая документация

Данный функционал позволяет ТСП (Торгово-сервисным предприятиям) выполнять привязку банковского счёта клиента для проведения последующих платежей без участия плательщика (рекуррентные платежи, оплата в один клик).


1. Привязка счёта без оплаты

Используется для регистрации QR-кода, целью которого является только установление связки между счётом клиента и ТСП.

1.1. Метод RegQRcSub

Параметры запроса:

Параметр Тип Обяз. Описание
command String Да Тип запроса. Константа: RegQRcSub.
TermNo String Да Уникальный идентификатор терминала.
qrcType String Да Тип QR-кода. Константа: 03.
subscriptionPurpose String Да Цель привязки. Отображается клиенту в приложении банка.
queryData.notificationUrl String Да URL для получения уведомления о результате привязки.
qrTtl String Нет Срок жизни ссылки в минутах (1 — 129 600). По умолчанию: 4320 (3 суток).
redirectUrl String Нет Ссылка для возврата клиента в приложение/на сайт ТСП.
subscriptionServiceId String(32) Нет Идентификатор сервиса подписки (используется с subscriptionServiceName).
subscriptionServiceName String(70) Нет Наименование сервиса подписки.

Пример запроса:

{
    "command": "RegQRcSub",
    "TermNo": "90080567",
    "qrTtl": "10",
    "qrcType": "03",
    "subscriptionPurpose": "Подписка на оплату услуг Интернет 500р./мес.",
    "queryData": {
        "notificationUrl": "https://sbp-subscription.example.com"
    },
    "redirectUrl": "https://exampletsp.io/callback"
}

Параметры ответа:

Параметр Описание
ErrorCode Код ответа (0 или RQ00000 — успех).
qrcId Идентификатор QR-кода.
payload Платежная ссылка для формирования QR или перехода.
payrrn Референс запроса в системе Банка.

1.2. Нотификация о результате привязки (subscription/notification)

Банк отправляет POST-запрос на notificationUrl ТСП.

Параметры нотификации:

  • status: ACWP (оформлено) или RJCT (отказ).
  • subscriptionToken: Уникальный токен привязки (необходим для будущих оплат).
  • memberId: Идентификатор банка плательщика.

Важно: Значения subscriptionToken и memberId необходимо сохранить. Без них проведение платежей по инициативе ТСП невозможно.


2. Оплата с последующей привязкой счёта

Позволяет клиенту совершить первую покупку и одновременно разрешить ТСП списывать средства в будущем.

2.1. Метод GetQRCd (Тип 02)

Для этого сценария используется стандартный метод генерации QR, но с обязательным заполнением поля subscriptionPurpose.

Ключевые параметры:

  • qrcType: 02 (динамический QR).
  • amount: Сумма первого платежа в копейках.
  • subscriptionPurpose: Описание подписки (наличие этого поля активирует сценарий привязки).
  • queryData.notificationUrl_sub: (Опционально) Отдельный URL для уведомления именно о привязке.

Логика уведомлений:

  1. При успешной операции ТСП получает два callback-уведомления:
    • О статусе платежа (qrc/notification).
    • О статусе привязки (subscription/notification).
  2. Если платеж прошел, но клиент отказался от привязки — придет уведомление об успехе оплаты и уведомление об отказе в подписке.

3. Оплата с привязанного счёта (по инициативе ТСП)

Сценарий "бесшовной" оплаты без участия клиента. Проводится в два этапа.

Этап 1: Генерация ссылки через GetQRCd

Создается технический QR-код (тип 02), к которому будет "привязан" платеж.

  • paymentPurpose: Обязательно для заполнения.
  • amount: Сумма списания.

Этап 2: Запрос на списание QRCSubPayPetition

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

Параметры запроса:

Параметр Обяз. Описание
command Да QRCSubPayPetition
subscriptionToken Да Токен, полученный при регистрации привязки.
SenderMemberId Да Идентификатор банка плательщика (memberId).
qrcId Да ID QR-кода, созданного на Этапе 1.

Пример запроса:

{
    "command": "QRCSubPayPetition",
    "TermNo": "90080567",
    "subscriptionToken": "70LSS7DN18SJQRS10006DNPKLJL24B05",
    "SenderMemberId": "100000000008",
    "qrcId": "AD10000BBJKO23GB98LA1FGBRIHH3K89"
}

3.1. Статусы решения банка (resolution/notification)

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

Код Описание
RQ00030 Успех. Согласие на проведение платежа.
RQ05031 Отказ: Привязка не найдена (клиент мог её удалить).
RQ05060 Отказ: Недостаточно средств.
RQ05061 Отказ: Превышен лимит СБП.
RQ05063 Отказ: Подозрение на мошенничество.

4. Запрос статуса привязки

Если ТСП не получило callback, можно запросить статус привязки вручную.

Метод GetQRCSubStatus

Запрос:

{
  "command": "GetQRCSubStatus",
  "TermNo": "90080567",
  "qrcId": "BB1S002PRSK6SR3E9R7P0H077UKN1QVF"
}

Ответ (успешная привязка):

{
    "ErrorCode": 0,
    "status": "ACWP",
    "subscriptionToken": "70LSS7DN18SJQRS10006DNPKLJLAGT77",
    "memberId": "600000000015",
    "message": "OK"
}

Важные примечания для разработчиков

  1. Лимиты: Оплата с привязанного счета возможна на сумму до 1 000 000 руб. за одну операцию.
  2. Кодировка: Текстовые данные в ответах могут передаваться в формате urlencoded (например, %u0423%u0441%u043F%u0435%u0445 для слова "Успех").
  3. Безопасность: Система ТСП должна игнорировать неизвестные дополнительные параметры в уведомлениях от НСПК/Банка, не считая их ошибкой.
  4. Хранение данных: Потеря subscriptionToken делает невозможным рекуррентное списание. В этом случае потребуется повторная привязка через QR-код.

Цифровой рубль: Техническая документация по интеграции

Цифровой рубль (ЦР) — это третья форма национальной валюты, дополняющая наличные и безналичные средства. Счета цифрового рубля открываются на платформе Центрального банка, а доступ к ним осуществляется через мобильные приложения и интернет-банки коммерческих банков.

Прием платежей в ЦР осуществляется в рамках Универсального платёжного кода (УПК).


1. Динамический QR-код (Одноразовый УПК)

Динамический код формируется под конкретную операцию с фиксированной суммой.

1.1. Регистрация динамического УПК

Для генерации кода можно использовать существующий метод GetQRCd или специализированный метод ReqUniQr.

Метод ReqUniQr

Запрос направляется ТСП в Банк для регистрации универсальной платёжной ссылки в API СБП.

Параметры запроса:

Код ключа Тип данных Обяз. Назначение
command String Y Константа ReqUniQr
TermNo String Y Уникальный идентификатор терминала
amount Number O* Сумма в копейках (обязательна для uniQrType = 02)
uniQrType String Y Тип ссылки: 01 — многоразовая, 02 — одноразовая
mediaType String O Расширение QR-кода (напр., image/png)
width / height String O Размеры изображения в пикселях
paymentPurpose String O Назначение платежа
redirectUrl String O URL для возврата в приложение ТСП (ASCII/RFC3986)
messageID String O Уникальный GUID сообщения
qrTtl String O Срок жизни ссылки в минутах
queryData.notificationUrl String O URL для уведомления о статусе оплаты

Пример запроса:

{
  "command": "ReqUniQr",
  "TermNo": "90080567",
  "amount": "10000",
  "uniQrType": "02",
  "redirectUrl": "https://alfabank.ru/sme/payservice/sbp/",
  "mediaType": "image/png",
  "width": "600",
  "height": "600",
  "messageID": "f9aa54ff-a615-44b8-aa6c-acab655c89f8",
  "queryData": {
    "notificationUrl": "https://sbp-payments",
    "SenderFIO": "Иванов Иван Иванович"
  }
}

Параметры ответа:

  • ErrorCode: 0 — успех.
  • payload: Платёжная ссылка.
  • image: Изображение QR-кода в Base64.
  • uniQrId: Идентификатор ссылки.
  • status: Статус (обычно CREATED).

1.2. Проверка статуса оплаты динамического УПК

Используется метод GetUniQrStatus.

Специфические статусы для Цифрового рубля:

  • ENDD: Платёж в ЦР обработан, но финальный результат (успех/отказ) пока неизвестен.
  • ACDR: Платёж в ЦР успешно выполнен (аналог ACWP для СБП).

Структура блока data (массив Record) в ответе:

Ключ Описание
paymentServiceId PS0000000001 (СБП) или PS0000000002 (ЦР)
status NTST (не начат), RCVD (в процессе), ACWP (успех СБП), RJCT (отказ), ENDD (ЦР в обработке), ACDR (успех ЦР)

2. Кассовая платёжная ссылка (Многоразовый УПК)

Многоразовый код, который обычно размещается в кассовой зоне.

2.1. Регистрация кассового УПК

Метод: RegCashUniQr.

Особенности:

  • Позволяет привязать конкретный qrcId.
  • В настройках ТСП на стороне Банка должен быть обязательно указан счет ЦР (accountDR).

Пример ответа:

{
    "ErrorCode": "0",
    "message": "OK",
    "TermNo": "90080567",
    "payload": "https://qr.nspk.ru/BS2R003FS8EFGAVM852PQS13N894HDLU?type=01...",
    "image": "iVBORw0KGgoAAAANSUhEUgAAAlg...",
    "qrcId": "BS2R003FS8EFGAVM852PQS13N894HDLU",
    "status": "CREATED"
}

2.2. Изменение параметров кассового УПК

Метод ChangeAccForCashUniQr позволяет обновить привязанные счета или параметры терминала без смены самого QR-кода.

Ключевые параметры для изменения:

  • account: Новый счет для СБП.
  • accountDR: Новый счет для Цифрового рубля (строго 55 символов).
  • NewTermNo: Смена ID терминала.
  • NewMerchantId: Смена ID мерчанта в НСПК.

2.3. Проверка статуса кассового УПК

Метод: GetCashUniQrStatus.

Важные поля ответа:

  • paymentServiceId: Определяет, как заплатил клиент (PS0000000002 — Цифровой рубль).
  • cashRegisterQrcStatus: Статус самой ссылки (WAITING_PAYMENT, IN_PROGRESS, DEACTIVATED).

3. Нотификация об исполнении перевода (C2B)

Сообщение отправляется со стороны Банка на сервер ТСП при получении финального статуса платежа.

Метод: paymentDR/notification (POST запрос)

Параметры запроса:

Код ключа Тип данных Назначение
command String paymentDR/notification
uniQrId String Идентификатор платежа
operationId String ID операции на платформе ЦР
status String Статус (напр. ACWP или RCVD)
amount String Сумма в рублях (с разделителем-точкой)
timestamp ISO8601 Дата и время операции
payrrn String Референс платежа

Пример нотификации:

{
    "command": "paymentDR/notification",
    "uniQrId": "AD2000670LSS7DN18SJQDNP4B05KLJL1",
    "operationId": "546464AX45546",
    "status": "ACWP",
    "amount": "10241.21",
    "timestamp": "2024-08-01T10:15:00.000Z",
    "payrrn": "102345678912",
    "TermNo": "90080567",
    "merchantName": "Рога и Копыта",
    "purpose": "Кофе и булочка"
}

Ожидаемый ответ от ТСП:

  • HTTP 200 OK — уведомление успешно принято.
  • HTTP 500 — внутренняя ошибка (будет произведена повторная попытка).

Приложение: Справочник статусов (status)

Код Описание Применимость
NTST Платёж не начат СБП / ЦР
RCVD Платёж инициирован / в обработке СБП / ЦР
ACWP Платёж успешно выполнен СБП
RJCT Платёж отклонён СБП
ENDD Платёж обработан (результат уточняется) ЦР
ACDR Платёж успешно выполнен ЦР

Дополнительные методы API СБП (Альфа-Банк)

Данный документ содержит описание дополнительных методов API для работы с Системой Быстрых Платежей (СБП) через платежный шлюз (ПШ) Альфа-Банка.

Примечание: Таблицы кодов ответов (ErrorCode) и их расшифровок приведены в Приложении №2 к основной документации.


1. Запрос списка банков-участников СБП (GetBankList)

Метод используется ТСП для получения актуального списка банков, поддерживающих оплату через СБП.

1.1. Параметры запроса

Код ключа Тип данных Обяз. Назначение
command String (an-1..50) Y Тип запроса. Константа: GetBankList
messageID String (ans-1..1024) N Уникальный идентификатор сообщения (GUID)
BankMemberIdFilter String (n-11) N Фильтр по ID участника СБП (если нужен только один банк)

Пример запроса:

{
  "command": "GetBankList"
}

1.2. Параметры ответа

Код ключа Тип данных Обяз. Назначение
ErrorCode String (an-20) Y Код ответа
message String (ans-1024) Y Расшифровка кода ответа
BankList Array N Коллекция банков-участников
BankList.BankName String (an-50) N Наименование банка
BankList.BankID String (an-12) N Идентификатор участника СБП в НСПК
BankList.BankBIK String (n-9) N БИК банка (если передан из НСПК)

Пример успешного ответа:

{
  "ErrorCode": 0,
  "message": "Запрос обработан успешно",
  "BankList": [
    {
      "BankName": "Наименование банка 1",
      "BankID": "10000001100",
      "BankBIK": "044525823"
    },
    {
      "BankName": "Наименование банка N",
      "BankID": "10000001145",
      "BankBIK": "044525829"
    }
  ]
}

2. Блокирование QR-кода (BlockQRcId)

Запрос направляется для блокировки ранее сгенерированного QR-кода любого типа.

2.1. Параметры запроса

Код ключа Тип данных Обяз. Назначение
command String (an-1..50) Y Тип запроса. Константа: BlockQRcId
TermNo String (an-20) Y Уникальный идентификатор терминала
qrcId String (an-32) Y Идентификатор QR-кода
reason String (ans-1024) N Причина блокировки

Пример запроса:

{
  "command": "BlockQRcId",
  "TermNo": "90080567",
  "qrcId": "BS1R003FN6RS6HL48QMBFVO5C4K9GQRV",
  "reason": "Заказ 12345 направлен в стоп-лист"
}

2.2. Параметры ответа

Код ключа Тип данных Обяз. Назначение
ErrorCode String (an-20) Y Код ответа
TermNo String (an-20) Y Уникальный идентификатор терминала
message String (ans-1024) Y Расшифровка кода ответа

Пример успешного ответа (200 OK):

{
  "ErrorCode": 0,
  "TermNo": "90080567",
  "message": "OK"
}

3. Разблокирование QR-кода (UnblockQRcId)

Запрос используется для восстановления активности ранее заблокированного QR-кода.

3.1. Параметры запроса

Код ключа Тип данных Обяз. Назначение
command String (an-1..50) Y Тип запроса. Константа: UnblockQRcId
TermNo String (an-20) Y Уникальный идентификатор терминала
qrcId String (an-32) Y Идентификатор QR-кода

Пример запроса:

{
  "command": "UnblockQRcId",
  "TermNo": "90080567",
  "qrcId": "BS1R003FN6RS6HL48QMBFVO5C4K9GQRV"
}

3.2. Параметры ответа

Код ключа Тип данных Обяз. Назначение
ErrorCode String (an-20) Y Код ответа
TermNo String (an-20) Y Уникальный идентификатор терминала
message String (ans-1024) Y Расшифровка кода ответа

Пример успешного ответа:

{
  "ErrorCode": 0,
  "TermNo": "90080567",
  "message": "OK"
}

4. Список заблокированных QR-кодов (GetBlockedQRcIdList)

Запрос позволяет получить перечень всех заблокированных QR-кодов по конкретному терминалу или кассе.

4.1. Параметры запроса

Код ключа Тип данных Обяз. Назначение
command String (an-1..50) Y Тип запроса. Константа: GetBlockedQRcIdList
TermNo String (an-20) Y Уникальный идентификатор терминала

Пример запроса:

{
  "command": "GetBlockedQRcIdList",
  "TermNo": "90080567"
}

4.2. Параметры ответа

Код ключа Тип данных Обяз. Назначение
ErrorCode String (an-20) Y Код ответа
message String (ans-1024) Y Расшифровка кода ответа
TermNo String (an-20) Y Уникальный идентификатор терминала
QRcIdList Collection N Список заблокированных QR-кодов
QRcIdList.qrcId String (an-32) Y Идентификатор QR-кода
QRcIdList.reason String (ans-1024) N Причина блокировки
QRcIdList.date String (an-20) Y Дата и время блокировки

Пример успешного ответа:

{
  "ErrorCode": 0,
  "TermNo": "90080567",
  "message": "OK",
  "QRcIdList": [
    {
      "date": "2024-04-18 17:17:45",
      "qrcId": "BD100000K5II0G369JHR3KBA6SM3FD3V",
      "reason": "Заказ 12345 направлен в стоп-лист"
    },
    {
      "date": "2024-05-01 19:07:15",
      "qrcId": "BD100002JN871TSC9SJB7HPVRFD3HQ8T",
      "reason": "Заказ 96780 направлен в стоп-лист"
    }
  ]
}

Обработка ошибок (Общий формат)

В случае ошибки (например, 400 Bad Request), шлюз возвращает JSON следующего вида:

{
  "ErrorCode": "Код ошибки",
  "message": "Расшифровка причины ошибки"
}

Приложения к технической спецификации СБП

Приложение 1. Формат Payload

В Системе быстрых платежей (СБП) используется формат двухмерного кода QR Code (ISO/IEC 18004-2015). Payload (полезная нагрузка) может быть представлен в двух вариантах.

Варианты Payload

  • Короткий вариант: https://{HOST}/{QR_ID}
  • Длинный вариант: https://{HOST}/{QR_ID}?type={QR_TYPE}&bank={MEMBER_ID}&sum={SUM}&cur={CUR}&crc={CRC}

Описание параметров URL-based payload

Параметр Описание Обяз. Формат
HOST qr.nspk.ru — для QR_TYPE 01 и 02
sub.nspk.ru — для QR_TYPE 03
y String
QR_ID Идентификатор зарегистрированного QR-кода в СБП y String (32 симв.)
QR_TYPE Тип QR-кода:
01 — QR Static (наклейка)
02 — QR Dynamic (на кассе)
03 — QR-Subscription (привязка счета)
y String (2 цифры)
MEMBER_ID Идентификатор Банка Получателя (ТСП) y String (12 симв.)
SUM Сумма в копейках. Обязательна для типа 02. Отсутствует для типа 03. y/o String (до 12 цифр)
CUR Валюта операции (обязательна, если присутствует SUM) y/o String (3 симв.)
CRC Значение контрольной суммы y String (4 симв.)

Приложение 2. Описание кодов ответа

Полный перечень кодов представлен на сайте НСПК. Коды, не описанные ниже, следует обрабатывать как техническую (системную) ошибку.

Общие коды ошибок системы

Код Сообщение / Описание
0 OK (Успешно)
-999 Прочее сообщение FSCryptoProxy
-71 Неверные данные Basic-авторизации запроса
-9 Система перегружена. Повторите запрос позже
-7 Неверная подпись сообщения (ошибка ключей)
-6 Не передана подпись в заголовке Authorization
-1 Возникли проблемы при обработке запроса
1 Внутренняя ошибка
2 Терминал не обнаружен
8 Таймаут ответа
25 Терминал заблокирован
1001 Сервис временно недоступен

Коды ОПКЦ СБП (RQ-серия)

Код Описание
RQ00000 Запрос обработан успешно
RQ03001 Ошибка валидации. Неверный формат запроса
RQ05002 Участник (memberId) не найден в СБП
RQ05005 ТСП (merchantId) не зарегистрировано в СБП
RQ05009 Сумма (amount) меньше минимально допустимой
RQ05010 Сумма (amount) больше максимально допустимой
RQ05014 Идентификатор qrcId не найден
RQ05032 Отказ Банка Плательщика в выполнении платежа
RQ05040 Сумма возврата превышает сумму исходной операции
RQ07999 Техническая ошибка

Ошибки по конкретным методам

Метод GetQRCd (Запрос QR-кода)

Код Описание
3 Не заполнены данные запроса
28 Запрос QR-кода не удался, не получен QR_ID
301 Некорректно заполнены данные
999* Неизвестная ошибка. Требуется уточнение статуса

Метод GetQRCstatus (Статус платежа)

Код Описание
4 Не передан qrcId или payrrn
5 Не получены данные от СБП
18 Платеж не найден в запросах B07, B23

Методы возврата (GetQRCreversalData, QRCreversal)

Код Описание
12 Не найдены данные для возврата
20 Получен отказ на запрос возврата
22 Несоответствие payrrn и qrcId в запросе
27 Возврат невозможен: счет зачисления не равен счету списания
121 Операция оплаты еще не имеет финального статуса
201 Отказ: Недостаточно средств на счете для возврата

Коды callback-уведомлений (Оплата с привязанного счета)

Используются в методе resolution/notification.

Код Описание
RQ05060 Недостаточно денежных средств
RQ05061 Превышен лимит по сумме операций СБП
RQ05063 Подозрение в мошенничестве (Anti-fraud)
RQ05065 Счет заблокирован
RQ05067 Запрещено по требованию законодательства

Примечание: Использование кода RQ05032 допускается не более чем в 20% случаев от общего числа отказов Банка Плательщика.


Приложение 3. Пояснение для колонки «Required»

Метка Значение
y Yes — обязательное поле
o Optional — опциональное поле
y/o Conditional — условно обязательное (зависит от условий запроса)

Приложение 4. Типы данных

Нотация Описание
a Символы латинского (A-Z, a-z) и русского (А-Я, а-я) алфавитов.
n Цифры 0-9.
an Буквенно-цифровой формат (смесь a и n).
ans Буквенно-цифровой формат со спецсимволами (пробел, пунктуация, знаки №, % и т.д.).

Кодировка: Все данные передаются в кодировке UTF-8.