Интеграция SberPay SDK Web

Обновлено 27 октября 2025

Установка

Npm

Поскольку SberPay SDK Web (SberPay Widget) в настоящее время распространяется в виде файла .tgz и не доступен в реестре NPM, вы можете установить ее, указав путь к файлу .tgz в вашем проекте:

1. Скачайте файл sberpay-widget-x.y.z.tgz в директорию вашего проекта.
2. Откройте терминал и перейдите в корневую директорию вашего проекта.
3. Выполните следующую команду, заменив /path/to/ на фактический путь к файлу .tgz:

npm install /path/to/sberpay-widget-x.y.z.tgz

Библиотека поддерживает Node.js >= 14.

UMD

Вы можете использовать универсальную UMD сборĸу, если в вашем проекте не используется пакетный менеджер npm. Чтобы получить файл, ĸоторый можно подĸлючить в виде сĸрипта нужно:

1. Распаĸовать архив:

tar -xzf sber-ecom-core-sberpay-widget-x.x.x.tgz

2. Переместить файл ./package/dist/index.umd.cjs в ваш проеĸт и подĸлючить его:

<script src="index.umd.cjs"></script>

3. В глобальной области видимости будет доступен объеĸт виджета payment-widget.

Начало работы

Перед использованием SberPay SDK Web (SberPay Widget) необходимо импортировать библиотеку в ваш проект.

import { createWidget } from '@sber-ecom-core/sberpay-widget';

В случае использования UMD в глобальной области видимости будет доступен объеĸт виджета:

const { createWidget } = window['payment-widget'];

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

Создание экземпляра виджета

Для создания нового экземпляра виджета используйте метод createWidget:

const widget = createWidget(environment);

Где environment - среда запуска виджета: PRODUCTION.

Открытие виджета

Для стандартного режима работы вызовите метод open у вашего экземпляра виджета:

widget.open(params);

Для режима оплаты карточной связкой вызовите метод bindingPayment у вашего экземпляра виджета:

widget.bindingPayment(params);

params - объект, содержащий параметры запуска виджета.

В десктопной версии откроется side drawer с приложением Сберпей, в мобильной - новый таб.

Пример для стандартного режима работы:

type WidgetParams = {
    bankInvoiceId: string;
    backUrl: string;
    lifeTime?: number;
    expirationDate?: number;
    isFinishPage?: true;
    finishPageTimeOut?: 10;

};

Пример для режима оплаты карточной связкой:

type WidgetParams = {
    bankInvoiceId: string;
    backUrl: string;
    bindingId?: b6c15da1-dd13-a64c-42d9-4c5ca70ab183;
    userName?: ЮМани;
    lifeTime?: number;
    expirationDate?: number;
    isFinishPage?: true;
    finishPageTimeOut?: 10;

};

Параметр	Тип	Обязательное значение	Описание
bankInvoiceId	string	Да	Значение orderId (в случае использования шлюза ecommerce.sberbank.ru) или sbolBankInvoiceId (в случае использования 3dsec.sberbank.ru).
backUrl	string	Да	Адрес по которому будет перенаправлен плательщик после завершения сценария SberPay SDK.
bindingId	string	Нет	Идентификатор связки на стороне мерчанта. Обязателен при запуске библиотеки методом bindingPayment.
userName	string	Нет	Логин партнера. Обязателен при запуске библиотеки методом bindingPayment.
lifeTime	number	Нет	Время жизни заказа в миллисекундах. Рассчет производится с момента, когда пользователь нажал на кнопку SberPay. Значение по умолчанию 1200000 мс.
expirationDate	number	Нет	Время, когда заказ будет просрочен, в формате unix-time.
isFinishPage	boolean	Нет	Признак отображения статусного экрана внутри SDK. Значение по умолчанию true.
finishPageTimeOut	boolean	Нет	Время (сек) отображения статусного экрана внутри SDK до редиректа по backUrl.

Параметры lifeTime и expirationDate передавать не обязательно, если во время регистрации заказа не задается время его жизни. Если переданы оба параметра, то приоритет будет у expirationDate.

Завершение сценария

После завершения сценария будет произведено перенаправление по адресу, указанному в backUrl. Дополнительно в параметры адреса будет добавлено значение state:

• success – оплата успешно прошла, требуется отправить на успешный экран
• return – в сценарии оплаты произошла ошибка, требуется отправить на неуспешный экран
• cancel – Клиент нажал на кнопку «Отменить». Актуально только для мобильной версии. В десктопной версии виджет закрывается, промис разрешается со значением 'cancel'.

Также будет добавлен параметр bankInvoiceId.

Например, если передан адрес: https://merchant.example.com/backUrl то в случае успеха будет произведен переход по адресу: https://merchant.example.com/backUrl?state=success&bankInvoiceId=729a0130-968a-41dc-883e-6918c8cc06c1

Закрытие виджета

Чтобы закрыть side drawer в десктопной версии используйте метод close:

widget.close();

Пример кода

import { createWidget } from '@sber-ecom-core/sberpay-widget';

const widget = createWidget(config.env);

const handleClick = async () => {
    const params = {
        bankInvoiceId, // '729a0130-968a-41dc-883e-6918c8cc06c1'
        backUrl: 'https://merchant.example.com/backUrl',
    };
    widget.open(params);
};