forked from apoloz/alfa-bank-sdk
1463 lines
70 KiB
Markdown
1463 lines
70 KiB
Markdown
## Главная
|
||
### Инструкция по интеграции СБП 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**.
|