@qrexpress/sbp-c2b-widget NPM

SBP C2B Widget

Описание

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

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

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

npm.io

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

npm.io

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

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

Установка

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

npm install @qrexpress/sbp-c2b-widget

или

yarn add @qrexpress/sbp-c2b-widget

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

Импорт

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>

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

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.

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.

SBP widget

@qrexpress/sbp-c2b

1.0.0

6 months ago