Обработка событий виджета
Виджет умеет уведомлять о событиях, которые с ним происходят, например о том, что пользователь завершил оплату или закрыл всплывающее окно, в котором отображается платежная форма. Вы можете обрабатывать такие события, чтобы реализовать более гибкую логику взаимодействия с пользователем.
 
События виджета
У виджета ЮKassa есть две группы событий: события процесса оплаты и события платежной формы.
  • События процесса оплаты связаны со статусом подтверждения платежа пользователем. Виджет может уведомлять вас просто о факте завершения оплаты или о конкретном статусе (успешно или нет). Обработка этих событий нужна, если вас не устраивает автоматическое перенаправление пользователя на 
    return_url
    и вы хотите реализовать собственную логику завершения платежа.
  • События платежной формы связаны с действиями пользователя на платежной форме. Сейчас виджет может уведомлять только о закрытии всплывающего окна. Это событие нужно использовать, только если вы отображаете виджет во всплывающем окне.
Для обработки события виджета вызовите метод
on
, передайте в него код события и callback-функцию с вашим кодом. При наступлении события виджет вызовет callback-функцию.
 
Обработка событий процесса оплаты
По умолчанию после платежа виджет перенаправляет пользователя на страницу завершения оплаты —
return_url
в скрипте для инициализации виджета. Если такая логика вас не устраивает, вы можете реализовать собственную, обрабатывая события процесса оплаты.
Вы можете выбрать один из двух сценариев:
Если сработало событие процесса оплаты, сначала проверьте статус платежа: подождите, когда придет уведомление от ЮKassa, или периодически отправляйте запросы, чтобы получить информацию о платеже .
 
Простое уведомление о завершении оплаты
В этом сценарии вам необходимо обработать только одно событие —
complete
(оплата завершена). Событие возникает в следующих случаях:
  • пользователь успешно ввел данные и подтвердил платеж;
  • пользователь выбрал оплату из кошелька ЮMoney или через SberPay/Сбербанк Онлайн, но платеж не прошел;
  • если вы отключили обработку неуспешных попыток в виджете: пользователь выбрал оплату банковской картой, через Apple Pay или Google Pay, но платеж не прошел;
  • закончился срок действия токена.
Для обработки события:
Шаг 1. Проверьте, что в скрипте отсутствует
return_url
. Если оставить
return_url
, события обрабатываться не будут.
Шаг 2. Вызовите метод
on
, передайте в него код
complete
и callback-функцию с методом
destroy
и вашим кодом.
Метод
destroy
нужен, чтобы после наступления события вы при необходимости могли заново инициализировать виджет и отобразить пользователю платежную форму.
HTML
<!--Подключение библиотеки-->
<script src="https://yookassa.ru/checkout-widget/v1/checkout-widget.js"></script>

<!--HTML-элемент, в котором будет отображаться платежная форма-->
<div id="payment-form"></div>

<script>
    //Инициализация виджета.
    const checkout = new window.YooMoneyCheckoutWidget({
        confirmation_token: 'confirmation-token', //Токен, который перед проведением оплаты нужно получить из API ЮKassa

        error_callback: function(error) {
            //Обработка ошибок инициализации
        }
    });

    checkout.on('complete', () => {
        //Код, который нужно выполнить после оплаты.

        //Удаление инициализированного виджета
        checkout.destroy();
    });

    //Отображение платежной формы в контейнере
    checkout.render('payment-form');
</script>
 
Уведомление о завершении оплаты с детализацией статуса
В этом сценарии вам необходимо обработать два события —
success
(оплата завершена успешно) и 
fail
(оплата завершена неудачно). Событие
success
возникает, когда пользователь успешно ввел данные и подтвердил платеж. Событие
fail
возникает в следующих случаях:
  • пользователь выбрал оплату из кошелька ЮMoney или через SberPay/Сбербанк Онлайн, но платеж не прошел;
  • если вы отключили обработку неуспешных попыток в виджете: пользователь выбрал оплату банковской картой, через Apple Pay или Google Pay, но платеж не прошел;
  • закончился срок действия токена.
Для обработки событий:
Шаг 1. Проверьте, что в скрипте отсутствует
return_url
. Если оставить
return_url
, события обрабатываться не будут.
Шаг 2. Вызовите метод
on
, передайте в него код
success
и callback-функцию с методом
destroy
и кодом, который необходимо выполнить при успешном завершении оплаты.
Шаг 3. Вызовите метод
on
, передайте в него код
fail
и callback-функцию с методом
destroy
и кодом, который необходимо выполнить при неудачном завершении оплаты.
Метод
destroy
нужен, чтобы после наступления события вы при необходимости могли заново инициализировать виджет и отобразить пользователю платежную форму.
HTML
<!--Подключение библиотеки-->
<script src="https://yookassa.ru/checkout-widget/v1/checkout-widget.js"></script>

<!--HTML-элемент, в котором будет отображаться платежная форма-->
<div id="payment-form"></div>

<script>
    //Инициализация виджета.
    const checkout = new window.YooMoneyCheckoutWidget({
        confirmation_token: 'confirmation-token', //Токен, который перед проведением оплаты нужно получить из API ЮKassa

        error_callback: function(error) {
            //Обработка ошибок инициализации
        }
    });

    checkout.on('success', () => {
            //Код, который нужно выполнить после успешной оплаты.

            //Удаление инициализированного виджета
            checkout.destroy();
        });

    checkout.on('fail', () => {
            //Код, который нужно выполнить после неудачной оплаты.

            //Удаление инициализированного виджета
            checkout.destroy();
        });

    //Отображение платежной формы в контейнере
    checkout.render('payment-form')
</script>
 
Обработка событий платежной формы
Виджет может уведомлять вас о том, что пользователь закрыл всплывающее окно с платежной формой (событие
modal_close
). Вы можете обрабатывать это событие, чтобы реализовать дополнительную логику взаимодействия с пользователем, например при закрытии окна сообщить пользователю, что оплата не завершена.
Для обработки события:
Шаг 1. Проверьте, что отображаете виджет во всплывающем окне: при инициализации виджета в объекте
customization
передан параметр
modal
со значением
true
. Если виджет размещен на странице оплаты, событие обрабатываться не будет.
Шаг 2. Вызовите метод
on
, передайте в него код
modal_close
и callback-функцию с кодом, который необходимо выполнить при закрытии всплывающего окна.
HTML
<!--Подключение библиотеки-->
<script src="https://yookassa.ru/checkout-widget/v1/checkout-widget.js"></script>

<script>
    //Инициализация виджета.
    const checkout = new window.YooMoneyCheckoutWidget({
        confirmation_token: 'confirmation-token', //Токен, который перед проведением оплаты нужно получить из API ЮKassa

        error_callback: function(error) {
            //Обработка ошибок инициализации
        }
    });

    checkout.on('modal_close', () => {
        //Код, который нужно выполнить после закрытия всплывающего окна.

    });

    //Отображение платежной формы во всплывающем окне
    checkout.render();
</script>

Есть вопросы или замечания по документации?

Можем созвониться и обсудить их лично: мы поможем вам разобраться, а вы нам — понять, что тут нужно улучшить. Для этого оставьте свои контакты и выберите время.
Да, хочу обсудить
 
Что почитать еще
Типовые сценарии интеграции виджетаПроведение платежейВходящие уведомленияСправочник виджета