npm package: @qrexpress/sbp-c2b-widget
Description: Виджет для интеграции с Системой Быстрых Платежей (СБП) через динамические QR-коды
Author: qrexpress
Latest version: 1.0.0

# SBP C2B Widget

## Описание
SBP Widget — это виджет для интеграции с Системой Быстрых Платежей (СБП) от **ТРР «Золотая корона»** с использованием динамических QR-кодов. Виджет позволяет создавать платежи, отображать QR-коды, а также отслеживать статусы транзакций.

---

### Как выглядит виджет

Экран по умолчанию, без показа QR-кода

![](https://i.imgur.com/Rlq3gxK.png)

Экран отображающий используемый QR-код

![](https://i.imgur.com/yiMDccd.png)

---

### Основные возможности:
- Генерация платежей с использованием динамических QR-кодов.
- Отображение статусов транзакций.
- Поддержка кастомизации через параметры.
- Реализация событий для взаимодействия с системой.

---

## Установка
Установите виджет через npm или yarn:

```bash
npm install @qrexpress/sbp-c2b-widget
```

или

```bash
yarn add @qrexpress/sbp-c2b-widget
```

---

## Использование

### Импорт

```javascript
import initSbpWidget from '@qrexpress/sbp-c2b-widget';
```

### Инициализация

Для инициализации виджета необходимо добавить контейнер, в который будет помещен виджет. 
По умолчанию виджет использует контейнер с `id="sbp-c2b-qr"`.
Если используется кастомный `wrapperId`, то нужно использовать `id` из этого параметра:

```
<div id="sbp-c2b-qr"></div>
```

или

```
<div id="custom-wrapper-id"></div>
```

Затем используйте параметры, описанные ниже:

```javascript
const widget = initSbpWidget({
  token: 'your_token',
  entityId: 'your_entity_id',
  merchantId: 'your_merchant_id',
  account: 'your_account',
  className: 'custom-class',
  options: {
    qrSize: 300,
    wrapperId: 'custom-wrapper-id',
    placeHolderSrc: 'base64-image-string',
  },
  onReady: () => console.log('Widget is ready'),
  onDestroy: () => console.log('Widget destroyed'),
  onQrcGenerate: (event) => console.log('QR code generated', event),
  onPollingStep: (event) => console.log('Polling step', event),
  onSBPFinal: (event) => console.log('Transaction completed', event),
  onError: (error) => console.error('Error occurred', error),
});

widget.render();
```

---

## Параметры конструктора

| Параметр         | Тип          | Обязательный | Описание                                                                |
|------------------|--------------|--------------|-------------------------------------------------------------------------|
| `token`          | `string`     | Да           | Секретный токен для авторизации.                                        |
| `entityId`       | `string`     | Да           | ID ЮЛ                                                                   |
| `merchantId`     | `string`     | Да           | ID ТСП                                                                  |
| `account`        | `string`     | Да           | Счет для платежа.                                                       |
| `className`      | `string`     | Нет          | Пользовательский класс для корневого элемента виджета.                  |
| `options`        | `Object`     | Нет          | Дополнительные настройки виджета (см. ниже).                            |
| `onReady`        | `Function`   | Нет          | Callback, вызываемый после успешного рендеринга виджета.                |
| `onDestroy`      | `Function`   | Нет          | Callback, вызываемый при удалении виджета.                              |
| `onQrcGenerate`  | `Function`   | Нет          | Callback, вызываемый при успешной генерации QR-кода.                    |
| `onPollingStep`  | `Function`   | Нет          | Callback, вызываемый при каждом шаге опроса статуса транзакции.         |
| `onSBPFinal`     | `Function`   | Нет          | Callback, вызываемый при завершении транзакции.                         |
| `onError`        | `Function`   | Нет          | Callback, вызываемый при возникновении ошибки.                          |

### Параметры объекта `options`:

| Параметр         | Тип      | Значение по умолчанию  | Описание                                                                |
|------------------|----------|------------------------|-------------------------------------------------------------------------|
| `qrSize`         | `number` | `400`                  | Размер QR-кода в пикселях.                                              |
| `requestLimit`         | `number` | `25`                  | Лимит запросов (по умолчанию 25).                                              |
| `pollingInterval`         | `number` | `2500`                  | Период между запросами статуса платежа в мс (по умолчанию 2500).                                              |
| `wrapperId`      | `string` | `sbp-c2b-qr`           | ID контейнера для размещения виджета.                                   |
| `placeHolderSrc` | `string` | `base64-заглушка`      | Изображение-заглушка для виджета.                                       |
| `hideQrcStatusLoader` | `boolean`| `false`           | Скрыть отображение индикатора опроса статуса.                           |
| `hideQrcLoader`    | `boolean`| `false`              | Скрыть отображение загрузки.                                            |
| `hideQrcHeader`  | `boolean`| `false`                | Скрыть отображение заголовка платежа.                                   |
| `hideQrcDescription` | `boolean`| `false`            | Скрыть отображение статуса транзакции.                                  |

---

## Методы

### `render()`
Рендерит HTML-контент виджета в указанной области DOM.

```javascript
widget.render();
```

### `initPaymentPolling(amount: number, paymentPurpose?: string)`
Инициализирует платеж и начинает опрос статуса транзакции.

```javascript
await widget.initPaymentPolling(5000, 'Оплата услуг');
```

### `stopPaymentPolling(reason?: string)`
Останавливает процесс опроса статуса транзакции.

```javascript
widget.stopPaymentPolling('Причина остановки');
```

### `showPaymentImage(sbpImage: string)`
Заменяет изображение QR-кода внутри виджета.

```javascript
widget.showPaymentImage('data:image/png;base64,...');
```

### `destroy()`
Полностью удаляет виджет из DOM и освобождает ресурсы.

```javascript
widget.destroy();
```
---

## Лицензия

Этот проект лицензирован под MIT License. Подробности в файле `LICENSE`.