Развернуть

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

Обновлено 28 сентября 2026

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

Установка

Npm

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

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

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

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

UMD

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

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

tar -xzf sberpay-widget-x.x.x.tgz

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

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

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

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

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

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

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

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

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

Функция getPersonalizationData

Асинхронная функция для получения персонализированных данных SberPay.

Сигнатура

const getPersonalizationData = async ({
  apiUrl,
  orderId,
}: GetPersonalizationDataParams) => Promise<PersonalizationData>;

Параметры запроса

Параметр	Тип	Формат	Описание	Обязательное значение
`orderId`	string	`^[0-9a-fA-F-]{32,36}\$`	Идентификатор заказа / номер счета СБОЛ. UUID с дефисами или без	Да
`apiUrl`	string	Константа https://ekompay.ru	Базовый URL для API запроса (если не указан, используется текущий origin)	Нет

Возвращаемое значение

{
  userInfo: {
    firstName: string;
    lastName: string;
    formattedCardNumber: string;
  };
  sessionId: string;
  loyaltyInfo?: {
    precalculateBonuses?: string;
    maxPointsAmount?: number;
  };
}

userInfo

Параметр	Тип	Формат	Описание	Обязательное значение
`firstName`	string	`^.{0,255}$`	Имя пользователя	Да
`lastName`	string	`^.{0,255}$`	Фамилия	Да
`formattedCardNumber`	string	`^[0-9a-fA-F]{4,19}$`	Номер карты, маскируется, показываются последние 4 цифры	Да

loyaltyInfo

Параметр	Тип	Формат	Описание	Обязательное значение
`precalculateBonuses`	string	maxLength: 30	Количество бонусов, которые будут начислены	Нет
`maxPointsAmount`	number	minimum: 0, maximum: 9999999999999.99	Максимальное количество баллов, которые можно использовать	Нет

Примеры использования

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

import { getPersonalizationData } from "@sber-ecom-core/sberpay-widget/personalization";

try {
  const data = await getPersonalizationData({
    orderId: "order-12345",
  });

  console.log("User Info:", data.userInfo);
  console.log("Session ID:", data.sessionId);

  if (data.loyaltyInfo) {
    console.log("Loyalty Info:", data.loyaltyInfo);
  }
} catch (error) {
  console.error("Ошибка при получении данных персонализации:", error);
}

С указанием кастомного API URL

import { getPersonalizationData } from "@sber-ecom-core/sberpay-widget/personalization";

try {
  const data = await getPersonalizationData({
    orderId: "order-12345",
    apiUrl: "https://custom-api.sberpay.ru",
  });

  console.log("Personalization data:", data);
} catch (error) {
  console.error("Ошибка:", error);
}

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

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

const widget = createWidget(environment);

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

Допустимые значения:

PRODUCTION – для промышленной среды
SANDBOX – для тестовой среды

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

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

widget.open(params);

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

widget.openBoundCardPayment(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}\$`	Идентификатор связки на стороне мерчанта. Обязателен при запуске библиотеки методом openBoundCardPayment.	Нет
`userName`	string	`^.{0,30}\$`	Логин партнера. Обязателен при запуске библиотеки методом openBoundCardPayment.	Нет
`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 без возможности изменить номер	Нет
`personalizedSessionId`	string	`^[0-9]{18,19}$`	Идентификатор сессии, полученный при персонализации кнопки SberPay	Нет

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

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

Оплата One-Click

Быстрая оплата при наличии персонализированных данных.

Для поддержки быстрой оплаты необходимо при открытии виджета дополнительно передать параметр personalizedSessionId (sessionId из результата вызова getPersonalizationData) в метод open

Пример использования

import { createWidget } from "@sber-ecom-core/sberpay-widget";
import { getPersonalizationData } from "@sber-ecom-core/sberpay-widget/personalization";

const data = await getPersonalizationData({ orderId: "order-12345" }); // stored some way data from getPersonalizationData

const widget = createWidget(env);

widget.open({
  ...otherWidgetParams,
  personalizedSessionId: data.sessionId,
});

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

После завершения сценария будет произведено перенаправление по адресу, указанному в 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. На тестовом контуре используются сертификаты НУЦ Минцифры. Для успешного тестирования необходимо установить и настроить доверие указанным сертификатам.

Тестирования в среде SandBox

Для проведения тестирования в среде SandBox требуется интегрировать библиотеку версии не ниже 0.8.2.

Для проверки сценария требуется запустить библиотеку в формате режима в Iframe, используя параметр isEmbedded. Далее в форме ввода номера телефона требуется ввести номер телефона 79447817393.

Ограничения режима SandBox

В тестовом контуре SandBox доступен стандартный режим оплаты. Режим оплаты карточной связкой и персонализация кнопки SberPay с оплатой One-Click не реализованы.

Заметили ошибку?

Выделите текст и нажмите

Ctrl

Enter

, чтобы сообщить нам об ошибке

Установка﻿

Npm﻿

UMD﻿

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

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

Функция getPersonalizationData﻿

Сигнатура﻿

Параметры запроса﻿

Возвращаемое значение﻿

userInfo

loyaltyInfo

Примеры использования﻿

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

С указанием кастомного API URL

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

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

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

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

Описание параметров﻿

Оплата One-Click﻿

Пример использования﻿

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

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

Пример кода﻿

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

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

Тестирования в среде SandBox﻿

Ограничения режима SandBox﻿