Handling widget events
The widget can send you notifications about events happening to it, for example, when a user finished a payment or closed the pop-up window where the payment form is displayed. You can handle these events to configure more flexible scenarios of interaction with users.
Widget events
The YooMoney widget has two types of events: payment process events and payment form events.
  • Payment process events refer to the payment confirmation status on user's side. The widget can notify you when a payment is finished in general or it can be more precise and inform you about the status (successful or unsuccessful). You can configure how these events are handled if redirecting users to
    return_url
    automatically is not enough for you and you'd like to set up a custom scenario of finishing payments.
  • Payment form events refer to user's actions on the payment form. Currently, the widget can only send notifications when the pop-up window gets closed. This event should only be used if you display the widget in a pop-up window.
To handle the event, call the 
on
method and specify the event code and callback function with your code in it. When the event occurs, the widget will call the callback function.
Payment process events
After the payment, the widget redirects users to the page for finishing the payment by default (
return_url
in the script for initializing the widget). If this scenario isn't suitable for you, you can set up your custom scenario and start handling payment process events.
You can select one of the following scenarios:
If a payment process event occurred, check the payment status first: wait until you receive a notification from YooMoney, or send periodic requests for information about the payment .
Simple notification when the payment is finished
In this scenatio, you only need to handle one event:
complete
(the payment is finished). This event occurs when:
  • user successfully entered the required information and confirmed the payment;
  • user selected the YooMoney wallet or SberPay as the payment method, but the payment was unsuccessful;
  • in case you disabled processing unsuccessful attempts in the widget: user selected bank card as the payment method, but the payment was unsuccessful;
  • the token has expired.
To handle the event:
Step 1. Make sure there's no
return_url
in the script. If you leave
return_url
there, events won't be handled.
Step 2. Call the 
on
method. In this method, enter the 
complete
code and the callback function with the 
destroy
method and your code.
The
destroy
method is required, so that, in case the event occurs, you could initialize the widget again display the payment form to the user if necessary.
HTML
<!--Library implementation-->
<script src="https://yookassa.ru/checkout-widget/v1/checkout-widget.js"></script>

<!--HTML element in which the payment form will be displayed-->
<div id="payment-form"></div>

<script>
    //Widget initialization.
    const checkout = new window.YooMoneyCheckoutWidget({
        confirmation_token: 'confirmation-token', //Token that must be obtained from YooMoney before the payment process

        error_callback: function(error) {
            //Processing of initialization errors
        }
    });

    checkout.on('complete', () => {
        //Code to be run after payment.

        //Deletion of an initialized widget
        checkout.destroy();
    });

    //Display of payment form in the container
    checkout.render('payment-form');
</script>
Notification when the payment is finished with information about the status
In this scenario, you need to handle two events:
success
(the payment was successful) and 
fail
(the payment was unsuccessful). The
success
event occurs when the user successfully entered the required information and confirmed the payment. The
fail
event occurs when:
  • user selected the YooMoney wallet or SberPay as the payment method, but the payment was unsuccessful;
  • in case you disabled processing unsuccessful attempts in the widget: user selected bank card as the payment method, but the payment was unsuccessful;
  • the token has expired.
To handle these events:
Step 1. Make sure there's no
return_url
in the script. If you leave
return_url
there, events won't be handled.
Step 2. Call the 
on
method. In this method, enter the 
success
code and the callback function with the 
destroy
method and your code to be run in case of a successful payment.
Step 3. Call the 
on
method. In this method, enter the 
fail
code and the callback function with the 
destroy
method and your code to be run in case of an unsuccessful payment.
The
destroy
method is required, so that, in case the event occurs, you could initialize the widget again display the payment form to the user if necessary.
HTML
<!--Library implementation-->
<script src="https://yookassa.ru/checkout-widget/v1/checkout-widget.js"></script>

<!--HTML element in which the payment form will be displayed-->
<div id="payment-form"></div>

<script>
    //Widget initialization.
    const checkout = new window.YooMoneyCheckoutWidget({
        confirmation_token: 'confirmation-token', //Token that must be obtained from YooMoney before the payment process

        error_callback: function(error) {
            //Processing of initialization errors
        }
    });

    checkout.on('success', () => {
            //Code to be run after successful payment.

            //Deletion of an initialized widget
            checkout.destroy();
        });

    checkout.on('fail', () => {
            //Code to be run after unsuccessful payment.

            //Deletion of an initialized widget
            checkout.destroy();
        });

    //Display of payment form in the container
    checkout.render('payment-form')
</script>
Payment form events
The widget can notify you when the user closes the pop-up window with the payment form (the
modal_close
event). You can handle this event to implement additional interaction with the user: for example, to inform the user that the payment is incomplete when the window gets closed.
To handle the event:
Step 1. Make sure you display the widget in a pop-up window: the 
modal
parameter with the 
true
value is specified in the 
customization
object upon widget initialization. If the widget is placed on the payment page, the event won't be handled.
Step 2. Call the 
on
method. In this method, enter the 
modal_close
code and the callback function with with code to be run in case the pop-up window gets closed.
HTML
<!--Library implementation-->
<script src="https://yookassa.ru/checkout-widget/v1/checkout-widget.js"></script>

<script>
    //Widget initialization.
    const checkout = new window.YooMoneyCheckoutWidget({
        confirmation_token: 'confirmation-token', //Token that must be obtained from YooMoney before the payment process

        error_callback: function(error) {
            //Processing of initialization errors
        }
    });

    checkout.on('modal_close', () => {
        //Сode to be run in case the pop-up window gets closed.

    });

    //Display of payment form in the pop-up window
    checkout.render();
</script>

Do you have any questions or comments regarding the documentation?

We can set up a call and discuss them: we'll help you solve the problem and you'll help us understand what we need to improve. To do that, share your contact information and select the time.
Yes, I'd like to set up a meeting
See also
Typical usage scenarios for the widgetPayment processNotificationsReference for widget