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

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

Для старта приёма оплат с помощью SberPay SDK требуется проведение настроек учетной записи (осуществляется службой технической поддержки интернет-эквайринга Support_ecomm@sberbank.ru в соответствии с условиями договора).

Установка

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 с приложением Сберпей, в мобильной - новый таб.

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

const widgetParams = {
    bankInvoiceId: '6a7ae0ec-16d1-429f-9c6d-162d1be8d3b8',
    backUrl: 'https://merchant.example.com/backUrl',
    lifeTime: 1200000,
    isFinishPage: true,
    finishPageTimeOut: 10,
    phone: '+70000000000',
    isPhoneChangeDisabled: true,
};

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

const widgetParams = {
    bankInvoiceId: '6a7ae0ec-16d1-429f-9c6d-162d1be8d3b8',
    backUrl: 'https://merchant.example.com/backUrl',
    bindingId: 'b6c15da1-dd13-a64c-42d9-4c5ca70ab183',
    userName: 'merchant_username',
    lifeTime: 1200000,
    isFinishPage: true,
    finishPageTimeOut: 10,
};

Параметр	Тип	Формат	Описание	Обязательное значение
bankInvoiceId	string	^[0-9a-fA-F-]{32,36}\$	Значение orderId (в случае использования шлюза ecommerce.sberbank.ru) или sbolBankInvoiceId (в случае использования 3dsec.sberbank.ru).	Да
backUrl	string	^.{1,255}\$	Адрес по которому будет перенаправлен плательщик после завершения сценария SberPay SDK. Требуется передавать аналогичное значение sberpay.backurl в запросе на регистрацию заказа в соответствии с документацией платежного шлюза: https://ecomtest.sberbank.ru/doc#tag/	Да
bindingId	string	^.{1,255}\$	Идентификатор связки на стороне мерчанта. Обязателен при запуске библиотеки методом bindingPayment.	Нет
userName	string	^.{0,30}\$	Логин партнера. Обязателен при запуске библиотеки методом bindingPayment.	Нет
lifeTime	number	minimum: 1, maximum: 9999999	Время жизни заказа в миллисекундах. Рассчет производится с момента, когда пользователь нажал на кнопку SberPay. Значение по умолчанию 1200000 мс.	Нет
expirationDate	number	minimum: 1, maximum: 2147483647	Время, когда заказ будет просрочен, в формате unix-time.	Нет
isFinishPage	boolean	-	Признак отображения статусного экрана внутри SDK. Значение по умолчанию true.	Нет
finishPageTimeOut	number	minimum: 1, maximum: 999	Время (сек) отображения статусного экрана внутри SDK до редиректа по backUrl.	Нет
phone	string	^+7\\d{10}\$	Номер телефона пользователя по которому предлагается провести авторизацию. Если передан авторизация осуществляется по номеру телефона	Нет
isPhoneChangeDisabled	boolean	-	Возможны следующие значения: true, false. Признак запрета изменения номера телефона при авторизации. Если истина авторизация осуществляется по номеру телефона переданному в phone без возможности изменить номер	Нет

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

Никакие передаваемые поля не могут содержать части html, javascript и другого кода.

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

После завершения сценария будет произведено перенаправление по адресу, указанному в 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);
};

Интеграция в iFrame / WebView

• Виджет для проведения авторизации и оплаты обращается к внешним ресурсам. Для корректной работы виджета на уровне WebView не должны быть заблокированы переходы на внешние ресурсы. В настройках делегатов навигации (WKNavigationDelegate) требуется разрешить любую навигацию без фильтрации по белым спискам (whitelist).
• Для определения WebView виджет использует User-Agent. Для корректной идентификации User-Agent должен содержать явное указание на использование WebView.
• Управление завершением сценария должно выполняться по факту получения backUrl. Закрытие iFrame / WebView с запущенным виджетом не должно осуществляться по событиям, отличным от указанных в спецификации.

Тестирование

Для проведения авторизации пользователя используется беспарольная авторизация Сбер ID. На тестовом контуре используются сертификаты НУЦ Минцифры. Для успешного тестирования необходимо установить и настроить доверие указанным сертификатам.