SBP C2B Widget

Описание

SBP Widget — это виджет для интеграции с Системой Быстрых Платежей (СБП) от ТРР «Золотая корона» с использованием динамических QR-кодов. Виджет позволяет создавать платежи, отображать QR-коды, а также отслеживать статусы транзакций.

Как выглядит виджет

Экран по умолчанию, без показа QR-кода

Экран отображающий используемый QR-код

Основные возможности:

• Генерация платежей с использованием динамических QR-кодов.
• Отображение статусов транзакций.
• Поддержка кастомизации через параметры.
• Реализация событий для взаимодействия с системой.

Установка

Установите виджет через npm или yarn:

npm install sbp-c2b-widget

или

yarn add sbp-c2b-widget

Использование

Импорт

import initSbpWidget from 'sbp-c2b-widget';

Инициализация

Для инициализации виджета необходимо добавить контейнер, в который будет помещен виджет. По умолчанию виджет использует контейнер с id="sbp-c2b-qr". Если используется кастомный wrapperId, то нужно использовать id из этого параметра:

<div id="sbp-c2b-qr"></div>

или

<div id="custom-wrapper-id"></div>

Затем используйте параметры, описанные ниже:

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-кода в пикселях. | | wrapperId | string | sbp-c2b-qr | ID контейнера для размещения виджета. | | placeHolderSrc | string | base64-заглушка | Изображение-заглушка для виджета. | | hideQrcStatusLoader | boolean| false | Скрыть отображение индикатора опроса статуса. | | hideQrcLoader | boolean| false | Скрыть отображение загрузки. | | hideQrcHeader | boolean| false | Скрыть отображение заголовка платежа. | | hideQrcDescription | boolean| false | Скрыть отображение статуса транзакции. |

Методы

render()

Рендерит HTML-контент виджета в указанной области DOM.

widget.render();

initPaymentPolling(amount: number, paymentPurpose?: string)

Инициализирует платеж и начинает опрос статуса транзакции.

await widget.initPaymentPolling(5000, 'Оплата услуг');

stopPaymentPolling(reason?: string)

Останавливает процесс опроса статуса транзакции.

widget.stopPaymentPolling('Причина остановки');

showPaymentImage(sbpImage: string)

Заменяет изображение QR-кода внутри виджета.

widget.showPaymentImage('data:image/png;base64,...');

destroy()

Полностью удаляет виджет из DOM и освобождает ресурсы.

widget.destroy();

Лицензия

Этот проект лицензирован под MIT License. Подробности в файле LICENSE.