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

Обновлено 14 июня 2024

Установка

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.

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

• npm
• umd

Перед использованием 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);

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

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

type WidgetParams = {
    bankInvoiceId: string;
    backUrl: string;
    lifeTime?: number;
    expirationDate?: number;
};

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

Параметры 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);
};