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

1463 lines
70 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
## Главная
### Инструкция по интеграции СБП 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](mailto:acquiring@alfabank.ru) |
#### Особенности обработки ошибок
* Каждый ответ содержит поле `ErrorCode`.
* При возникновении логической ошибки описание возвращается в поле `message`.
---
## 2. Процесс аутентификации
Для работы со шлюзом (и на тестовой, и на промышленной среде) используется двусторонняя аутентификация **MTLS** и подпись тела запроса.
### 2.1. Генерация сертификатов (Self-signed)
Клиент должен самостоятельно сгенерировать ключевую пару RSA для подписи запросов.
**Команда OpenSSL:**
```bash
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](mailto: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. **Вычисление хеша и подпись:**
```bash
# Расчет SHA256 и подпись приватным ключом
openssl dgst -sha256 -sign client.key -out signature.txt block.txt
```
3. **Кодирование в Base64:**
```bash
# Получение строки для заголовка Authorization
base64 signature.txt > signature64.txt
```
---
## 4. Тестирование
### 4.1. Эндпойнт тестовой среды
`https://217.12.103.132:2443/fsCryptoProxy`
### 4.2. Пример запроса (GetQRCd)
**Body:**
```json
{
"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](https://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](mailto: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 операция, и Агент ТСП получает уведомление о финальном статусе.
---
## Справочник параметров (Сниппеты данных)
При формировании запросов используйте следующие ключевые поля:
```json
// Пример ключевых полей для активации кассовой ссылки / оплаты
{
"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 для получения уведомления о статусе оплаты. |
### Пример запроса
```json
{
"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 | Маскированный номер телефона плательщика. |
### Пример уведомления
```json
{
"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 | Сумма возврата. Если пусто — полный возврат. |
**Пример ответа:**
```json
{
"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` — Статус неизвестен (в обработке).
### Пример ответа
```json
{
"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`: Наименование привязки.
### Пример запроса
```json
{
"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) — Операция в обработке.
### Пример ответа (Успех)
```json
{
"ErrorCode": 0,
"status": "ACWP",
"qrcId": "AD100026KQ0ESJBV8OFPCG0U9K1H52UM",
"trxId": "A3013090427361010000057B3DA2D4A7",
"amount": 10000,
"payerId": "*********1234"
}
```
---
## 3. Нотификация о финальном статусе
**Метод:** `qrc/notification`
Запрос отправляется со стороны Банка на `notificationUrl` ТСП.
### Формат уведомления
```json
{
"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 | Вернуть остаток доступных средств в ответе |
### Пример ответа на возврат
```json
{
"ErrorCode": 0,
"message": "Возврат проведен",
"amount": 10000,
"trxId": "A3024113609260070000086B8426B817",
"restAmount": "99.87"
}
```
---
## 5. История и статусы возвратов
### Запрос истории (`GetQRCreversalHistory`)
Позволяет получить список всех попыток возврата по одной транзакции оплаты.
**Пример структуры массива `refunds` в ответе:**
```json
"refunds": [
{
"status": "ACWP",
"amount": 10000,
"trxId": "B51390823097450W0000180011510503",
"trxDT": "20250519082345"
},
{
"status": "RJCT",
"amount": 10000,
"trxId": "A4327120041167130000020011381101"
}
]
```
---
## 6. Нотификация о возврате
**Метод:** `b2c-refund/notification`
Банк уведомляет систему ТСП о финальном статусе операции возврата.
### Пример уведомления
```json
{
"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-табличек |
**Пример запроса:**
```json
{
"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 для уведомления об оплате |
**Пример запроса:**
```json
{
"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) — В обработке.
**Пример ответа (Успех):**
```json
{
"ErrorCode": 0,
"status": "ACWP",
"trxId": "A30180803159571F0000097B3DA2D4A7",
"amount": 10000,
"payerId": "*********1234",
"payrrn": "000056251465"
}
```
---
## 4. Деактивация ссылки
Метод `DelCashQRc` используется для досрочной отмены ожидания оплаты (например, если клиент отказался от покупки).
**Пример запроса:**
```json
{
"command": "DelCashQRc",
"TermNo": "90080567",
"qrcId": "BS1R001P1UIGJCFJ9RDQ8974M1I4CJO9"
}
```
---
## 5. Возврат платежа
Возврат по СБП выполняется в два этапа (или в один при наличии `messageID`).
### Этап 1: Проверка возможности возврата (`GetQRCreversalData`)
Позволяет узнать доступный остаток и получить данные для проведения возврата.
### Этап 2: Проведение возврата (`QRCreversal`)
**Пример запроса на возврат:**
```json
{
"command": "QRCreversal",
"TermNo": "90080567",
"payrrn": "000056251465",
"amount": 10000,
"messageID": "f9aa54ff-a615-44b8-aa6c-acab655c89f8"
}
```
---
## 6. Нотификации (Webhooks)
Банк отправляет POST-запросы на ваш `notificationUrl` при изменении статуса оплаты или возврата.
### Уведомление об оплате (`qrc/notification`)
```json
{
"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) | Нет | Наименование сервиса подписки. |
**Пример запроса:**
```json
{
"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. |
**Пример запроса:**
```json
{
"command": "QRCSubPayPetition",
"TermNo": "90080567",
"subscriptionToken": "70LSS7DN18SJQRS10006DNPKLJL24B05",
"SenderMemberId": "100000000008",
"qrcId": "AD10000BBJKO23GB98LA1FGBRIHH3K89"
}
```
### 3.1. Статусы решения банка (`resolution/notification`)
После запроса на списание банк присылает уведомление с результатом:
| Код | Описание |
| :--- | :--- |
| `RQ00030` | **Успех.** Согласие на проведение платежа. |
| `RQ05031` | Отказ: Привязка не найдена (клиент мог её удалить). |
| `RQ05060` | Отказ: Недостаточно средств. |
| `RQ05061` | Отказ: Превышен лимит СБП. |
| `RQ05063` | Отказ: Подозрение на мошенничество. |
---
## 4. Запрос статуса привязки
Если ТСП не получило callback, можно запросить статус привязки вручную.
### Метод `GetQRCSubStatus`
**Запрос:**
```json
{
"command": "GetQRCSubStatus",
"TermNo": "90080567",
"qrcId": "BB1S002PRSK6SR3E9R7P0H077UKN1QVF"
}
```
**Ответ (успешная привязка):**
```json
{
"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 для уведомления о статусе оплаты |
**Пример запроса:**
```json
{
"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`).
**Пример ответа:**
```json
{
"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 | Референс платежа |
**Пример нотификации:**
```json
{
"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 участника СБП (если нужен только один банк) |
**Пример запроса:**
```json
{
"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 | БИК банка (если передан из НСПК) |
**Пример успешного ответа:**
```json
{
"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 | Причина блокировки |
**Пример запроса:**
```json
{
"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):**
```json
{
"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-кода |
**Пример запроса:**
```json
{
"command": "UnblockQRcId",
"TermNo": "90080567",
"qrcId": "BS1R003FN6RS6HL48QMBFVO5C4K9GQRV"
}
```
### 3.2. Параметры ответа
| Код ключа | Тип данных | Обяз. | Назначение |
| :--- | :--- | :---: | :--- |
| `ErrorCode` | String (an-20) | **Y** | Код ответа |
| `TermNo` | String (an-20) | **Y** | Уникальный идентификатор терминала |
| `message` | String (ans-1024) | **Y** | Расшифровка кода ответа |
**Пример успешного ответа:**
```json
{
"ErrorCode": 0,
"TermNo": "90080567",
"message": "OK"
}
```
---
## 4. Список заблокированных QR-кодов (`GetBlockedQRcIdList`)
Запрос позволяет получить перечень всех заблокированных QR-кодов по конкретному терминалу или кассе.
### 4.1. Параметры запроса
| Код ключа | Тип данных | Обяз. | Назначение |
| :--- | :--- | :---: | :--- |
| `command` | String (an-1..50) | **Y** | Тип запроса. Константа: `GetBlockedQRcIdList` |
| `TermNo` | String (an-20) | **Y** | Уникальный идентификатор терминала |
**Пример запроса:**
```json
{
"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** | Дата и время блокировки |
**Пример успешного ответа:**
```json
{
"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 следующего вида:
```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<br>`sub.nspk.ru` — для QR_TYPE 03 | y | String |
| **QR_ID** | Идентификатор зарегистрированного QR-кода в СБП | y | String (32 симв.) |
| **QR_TYPE** | Тип QR-кода:<br>01 — QR Static (наклейка)<br>02 — QR Dynamic (на кассе)<br>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**.