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_urlautomatically 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. При наступлении события виджет вызовет callback-функцию.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:
- Simple notification when the payment is finished: the widget notifies you when the payment is finished regardless of whether it's successful or not.
- Notification when the payment is finished with information about the status: the widget informs you if the payment was successful or not.
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 scenario, 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;
- in case you disabled processing unsuccessful attempts in the widget: user selected any 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: Событие fail возникает в следующих случаях:- in case you disabled processing unsuccessful attempts in the widget: user selected any 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 failed payment. //Deletion of an initialized widget checkout.destroy(); }); //Display of payment form in the container checkout.render('payment-form') </script>
Payment form events
Only for those who display the widget in a pop-up window
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>
See also