Инструкции
Помощь
Подключить ЮKassa
Обработка событий виджета
Виджет умеет уведомлять о событиях, которые с ним происходят, например о том, что пользователь завершил оплату или закрыл всплывающее окно, в котором отображается платежная форма. Вы можете обрабатывать такие события, чтобы реализовать более гибкую логику взаимодействия с пользователем.
События виджета
У виджета ЮKassa есть две группы событий: события процесса оплаты и события платежной формы.
  • События процесса оплаты связаны со статусом подтверждения платежа пользователем. Виджет может уведомлять вас просто о факте завершения оплаты или о конкретном статусе (успешно или нет). Обработка этих событий нужна, если вас не устраивает автоматическое перенаправление пользователя на return_url и вы хотите реализовать собственную логику завершения платежа.
  • События платежной формы связаны с действиями пользователя на платежной форме. Сейчас виджет может уведомлять только о закрытии всплывающего окна. Это событие нужно использовать, только если вы отображаете виджет во всплывающем окне.
Для обработки события виджета вызовите метод on, передайте в него код события и callback-функцию с вашим кодом. При наступлении события виджет вызовет callback-функцию.
Обработка событий процесса оплаты
По умолчанию после платежа виджет перенаправляет пользователя на страницу завершения оплаты — return_url в скрипте для инициализации виджета. Если такая логика вас не устраивает, вы можете реализовать собственную, обрабатывая события процесса оплаты.
Вы можете выбрать один из двух сценариев:
Простое уведомление о завершении оплаты
В этом сценарии вам необходимо обработать только одно событие — complete (оплата завершена). Событие возникает в следующих случаях:
  • пользователь успешно ввел данные и подтвердил платеж;
  • если вы отключили обработку неуспешных попыток в виджете: пользователь выбрал любой способ оплаты, но платеж не прошел;
  • закончился срок действия токена.
Для обработки события:
Шаг 1. Проверьте, что в скрипте отсутствует return_url. Если оставить return_url, события обрабатываться не будут.
Шаг 2. Вызовите метод on, передайте в него код complete и callback-функцию с методом destroy и вашим кодом.
HTML

<script src="https://yookassa.ru/checkout-widget/v1/checkout-widget.js"></script>


<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 возникает в следующих случаях:
  • если вы отключили обработку неуспешных попыток в виджете: пользователь выбрал любой способ оплаты, но платеж не прошел;
  • закончился срок действия токена.
Для обработки событий:
Шаг 1. Проверьте, что в скрипте отсутствует return_url. Если оставить return_url, события обрабатываться не будут.
Шаг 2. Вызовите метод on, передайте в него код success и callback-функцию с методом destroy и кодом, который необходимо выполнить при успешном завершении оплаты.
Шаг 3. Вызовите метод on, передайте в него код fail и callback-функцию с методом destroy и кодом, который необходимо выполнить при неудачном завершении оплаты.
HTML

<script src="https://yookassa.ru/checkout-widget/v1/checkout-widget.js"></script>


<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>
Что почитать еще
Типовые сценарии интеграции виджетаПроведение платежейВходящие уведомленияСправочник виджета