2. JS API (платёжный виджет)

Платёжный виджет — всплывающая или встраемая форма в сайт для оплаты любым доступным платёжным методом.

Виджет оптимизирован для использования во всех браузерах и мобильных устройствах. Виджет гарантирует безопасность передачи карточных данных по стандарту PCI DSS и не требует от ТСП сертификации для использования.

2.1 Параметры платёжного виджета

Платёжный виджет подключается тремя небольшими блоками HTML-кода (загрузка скрипта, кнопка оплаты, параметры платежа).

Инструкции по установке описаны в разделе 2.3.

Параметры платежа – это элементы структуры options – их можно передать при создании JS-объекта виджета или при вызове метода pay, который отображает платёжное окно.

Параметры:

widget_key	string	Открытый ключ для вызова платёжного виджета. Ключ виджета можно узнать в личном кабинете в настройках проекта. Обязательный параметр
amount	int	Сумма платежа в минорных единицах (копейках). От 100 (1₽) до 100000000 (1млн₽) для payment_method = card От 1000 (10₽) до 1500000 (15тыс₽) для payment_method = mobile Для конкретных проектов могут действовать более строгие ограничения. Обязательный параметр
description	string|null	Описание платежа. Отображается на платёжной форме и в личном кабинете ТСП. Необязательный параметр. По умолчанию "Оплата заказа". От 3 до 125 символов.
payment_method	string|null	Платёжный метод (см. раздел 6.8), который будет использован для совершения оплаты. Необязательный. По умолчанию не задан (все доступные методы).
merchant_payment_id	string|null	ID платежа в ТСП. Если передан, то это же значение параметра будет приходить в уведомлениях payment_status Необязательный параметр. От 1 до 256 символов.
merchant_campaign_id	string|null	ID кампании в ТСП. Если передан, то это же значение параметра будет приходить в уведомлениях payment_status Необязательный параметр. От 1 до 256 символов.
merchant_data	string|null	Произвольные данные ТСП, связанные с платежом. Если передан, то это же значение параметра будет приходить в уведомлениях payment_status Необязательный параметр. От 1 до 256 символов.
merchant_fields	json-object|null	Массив дополнительных сведений о транзакции, которые ТСП может передать при создании платежа. При уведомлении о статусе оплаты этот массив будет возвращен вместе с остальными параметрами в уведомлении payment_status Может применяться для передачи сопутствующих данных о плательщике или товаре: по значениям в массиве возможна фильтрация платежей в личном кабинете и выгружаемых XLS отчетах. Пример: { "Cookie": "HunjV5LHOvDIF", "client-category": "VIP", "Возраст": 33 } Необязательный параметр.
user_email	string|null	Email плательщика (если известен), для отправки email о совершённом платеже. Необязательный параметр.
user_name	string|null	Имя плательщика (если известно), для отправки email о совершённом платеже. Необязательный параметр.
user_phone	string|null	Номер телефона плательщика (если известен), только цифры, в международном формате, с кодом страны. Необязательный параметр.
user_comment	string|null	Пользовательский комментарий к платежу (если есть). Необязательный параметр.
user_account_id	string|null	Идентификатор пользователя в ТСП (если есть). Необязательный параметр.
test	int|null	Признак тестового платежа. 1: Платёж тестовый 0: Платёж реальный Для тестовых платежей необходимо указывать специальные номера банковских карт/номера телефонов (раздел 5.5). Необязательный параметр. По умолчанию 0 (Платёж реальный).
timeout	int|null	Время в секундах, отведенное на оплату. После окончания времени на оплату платёж получит статус таймаут и оплата по данному payment_id будет невозможна. Для повторной оплаты необходимо создать новый платёж. Необязательный параметр. По умолчанию 21600 (6 часов).
language	string|null	Язык платёжной формы, сервисных сообщений (см. раздел 6.2). Необязательный параметр. По умолчанию "RU" или "EN" в зависимости от IP пользователя.
currency	string|null	Валюта платежа (см. раздел 6.1). Необязательный параметр. По умолчанию RUB.
items	json-object|null	Данные для чека. Описание структуры – в разделе 3.7 Пример: [ { "name": "Xiaomi MI", "quantity": 2, "sum": 3500000, "vat": "vat20" } ] Необязательный параметр.
recurrent_payment	int|null	Признак установочного платежа для последующих безакцептных списаний в режиме рекуррентов (раздел 3.5) или в режиме подписки (раздел 3.4) 1: Платёж рекуррентный 0: Платёж обычный. Необязательный параметр. По умолчанию 0 (платёж обычный).
payment_scheme	string|null	Схема проведения платежа по банковским картам (см. раздел 4.3). Возможные значения см. в разделе 6.11 Необязательный параметр. По умолчанию "single".
utm_medium	string|null	UTM-метка, определяющая тип трафика. Если параметр передан, то это же значение параметра будет приходить в уведомлениях payment_status. Необязательный параметр.
utm_source	string|null	UTM-метка, определяющая источник трафика. Если параметр передан, то это же значение параметра будет приходить в уведомлениях payment_status. Необязательный параметр.
utm_campaign	string|null	UTM-метка, определяющая рекламную кампанию. Если параметр передан, то это же значение параметра будет приходить в уведомлениях payment_status. Необязательный параметр.
utm_term	string|null	Произвольная пользовательская UTM-метка. Если параметр передан, то это же значение параметра будет приходить в уведомлениях payment_status. Необязательный параметр.

2.2 Callback-функции

После успешной оплаты или в случае ошибки бывает необходимо совершить какие-либо действия: закрыть форму, переадресовать плательщика на другую страницу и так далее. Для этого можно настроить обработчики:

setSuccessCallback	function или string	Вызывается после получения статуса об успешной оплате. Указывается либо функция, либо адрес страницы сайта. Если указана функция, она будет вызвана после успешного завершения платежа. Если указан URL-адрес, пользователь будет направлен на данную страницу. Пример вызова функции: M.setSuccessCallback(function(o, i){ // действия при успешной оплате console.log('success'); }); Пример редиректа на другой url: M.setSuccessCallback('https://site.ru');
setFailCallback	function или string	Вызывается после получения статуса о неуспешной оплате. Указывается либо функция, либо адрес страницы сайта. Если указана функция, она будет вызвана после неуспешного завершения платежа. Если указан URL-адрес, пользователь будет направлен на данную страницу. Пример вызова функции: M.setFailCallback(function(o, i){ // действия при неуспешной оплате console.log('fail'); }); Пример редиректа на другой url: M.setFailCallback('https://site.ru');
setCloseCallback	function или string	Вызывается при закрытии виджета плательщиком в любой момент оплаты. Указывается либо функция, либо адрес страницы сайта. Если указана функция, она будет вызвана после закрытии виджета, когда платёж не завершен. Если указан URL-адрес, пользователь будет направлен на данную страницу. Пример вызова функции: M.setCloseCallback(function(o, i){ // действия при отмене платежа (закрытии виджета) console.log('close'); }); Пример редиректа на другой url: M.setCloseCallback('https://site.ru');
setProcessCallback	function	Вызывается в момент начала инициализации оплаты платежа. В данную функцию URL-адрес страницы перенаправления не может быть передан, поскольку процесс платежа только начат и пользователь должен находиться на странице банка. Не рекомендуется также использовать здесь тяжёлые скрипты, которые могут замедлить процесс оплаты. Пример вызова функции: M.setProcessCallback(function(o, i){ // действия в момент начала обработки платежа console.log('pending'); });

2.3 Вызов платёжного виджета

Для вызова платёжного виджета добавьте в HTML-код страницы три блока:

1. Загрузка js-скрипта Миксплат, разместите код в начале страницы, где вы подгружаете остальные скрипты.

<script async src="https://cdn.mixplat.ru/widget/v3/widget.js"></script>

2. Добавьте кнопку оплаты одним из вариантов, который применим к вашему сайту:

Элемент button

<button id="mixplat_widget">Оплатить</button>

Элемент input

<input type="button" id="mixplat_widget" value="Оплатить" />

Элемент href

<a href="#" id="mixplat_widget">Оплатить</a>

Элемент

<div id="mixplat_widget"></div>

3. Создайте экземпляр виджета и определите параметры платежа

Пример на JS

<script type="text/javascript">
document.addEventListener('DOMContentLoaded', function(){
        let elem = document.getElementById('mixplat_widget');
        elem.addEventListener('click', function(){
            
            let options = {
                widget_key: '1becc19b-d3e8-422f-bb28-14ec9d94e66b',
                amount: 1000, // 10 руб. 00 коп.
                description: 'Благотворительное пожертвование',
                payment_method: 'card',
                user_email: 'email@mail.ru',
                user_phone: '79031234567',
                merchant_payment_id: '1234567'
            }
            let M = new Миксплат(options);
            M.build();
            M.setSuccessCallback(function(o, i){
                console.log('success');
            });
            M.setFailCallback(function(o, i){
                console.log('fail');
            });
            
            M.setCloseCallback(function(o, i){
                console.log('close');
            });

        });
    });
</script>

Пример на jQuery

<script type="text/javascript">
$(function(){
        $('#mixplat_widget').on('click', function(){
            
            let options = {
                widget_key: '1becc19b-d3e8-422f-bb28-14ec9d94e66b',
                amount: 1000, // 10 руб. 00 коп.
                description: 'Благотворительное пожертвование',
                payment_method: 'card',
                user_email: 'email@mail.ru',
                user_phone: '79031234567',
                merchant_payment_id: '1234567'
            }

            let M = new Миксплат(options);
            M.build();
            M.setSuccessCallback(function(o, i){
                console.log('success');
            });
    
            M.setFailCallback(function(o, i){
                console.log('fail');
            });
            
            M.setCloseCallback(function(o, i){
                console.log('close');
            });

        });
    });
</script>

При необходимости реализуйте получение и обработку статуса платежа payment_status в бэкенде сайта.

Наличие или отсутствие скрипта-обработчика никак не влияет на проведение платежа для плательщика. Метод payment_status предназначен для асинхронной передачи данных о статусах платежей в бэкенд.

Для получения статусов необходимо подготовить скрипт-обработчик нотификаций метода payment_status и прописать его URL в настройках проекта в личном кабинете.

2.5 Пример кода страницы

В примере представлены 2 способа вызова виджета — в виде встроенного в страницу и всплываюшего по клику на кнопку.

Всплывающий по клику

<html lang="ru">
<head><meta charset="UTF-8">
<title>MIXPLAT widget test</title>
<script async src="https://cdn.mixplat.ru/widget/v3/widget.js"></script>
</head>
<body>
<!-- при клике на кнопку отобразится платёжная форма -->
<button id="mixplat_widget">Открыть в модальном окне</button>
<script type="text/javascript">
document.addEventListener('DOMContentLoaded', function(){
        let elem = document.getElementById('mixplat_widget');
        elem.addEventListener('click', function(){
        
            let options = {
                widget_key: '1becc19b-d3e8-422f-bb28-14ec9d94e66b',
                amount: 1000,  // 10 руб. 00 коп.
                description: 'Благотворительное пожертвование',
                user_email: 'email@mail.ru',
                recurrent_payment: 0
            }
            let M = new Миксплат(options);
            M.build();
            M.setSuccessCallback(function(o, i){
                console.log('success');
            });
            M.setFailCallback(function(o, i){
                console.log('fail');
            });
    
        });
    });
</script>
</body>
</html>

Встроенный в страницу

<html lang="ru">
<head><meta charset="UTF-8">
<title>MIXPLAT widget test</title>
<script async src="https://cdn.mixplat.ru/widget/v3/widget.js"></script>
</head>
<body>
<!-- в этом элементе будет отображаться встроенная в страницу платёжная форма -->
<div id="mixplat_widget"></div>

<script type="text/javascript">
window.addEventListener('load', function(){
        let options = {
            widget_key: '1becc19b-d3e8-422f-bb28-14ec9d94e66b',
            amount: 1000,  // 10 руб. 00 коп.
            description: 'Благотворительное пожертвование',
            user_email: 'email@mail.ru',
            recurrent_payment: 0
        }
        let M = new Миксплат(options, 'mixplat_widget');
        M.build();
        M.setSuccessCallback(function(o, i){
            console.log('success');
        });
        M.setFailCallback(function(o, i){
            console.log('fail');
        });
});
</script>
</body>
</html>

2.5 Демо работы виджета

Демонстрация работы виджета представлена на примере БФ «Русфонд». Для тестирования можно использовать любые доступные способы оплаты. Списание денежных средств произойдет на сумму 12 рублей. Средства будут переданы в благотворительный фонд в полном объёме.