Widget integration
Detailed manual for using the YooMoney Checkout Widget for payment acceptance. If you have already integrated using Quick start for widget and everything is working fine, you can skip this article.
Preliminary configuration
Implement the payment methods you need, set up your website, and prepare the payment page.
Payment method implementation
The widget supports several payment methods. The payment form will display the methods enabled in your store. You can check and enable payment methods in the Settings — Payment methods section of your Merchant Profile, or by contacting your YooMoney manager.
Some payment methods require certain conditions to be displayed in the payment form.
Payment methodAvailability
YooMoneyAvailable by default
Bank cardAvailable if the store is allowed to accept payments using this method
SberPayAvailable if the store is allowed to accept payments using this method.
FPS (Faster Payments System)Available if the store is allowed to accept payments using this method.
Configuring the website
The widget can display various messages to the user during the payment process. Add the UTF-8 support to your website so the user will be able to read it.
To check if your website meets these requirements, contact your hosting provider or test the website independently using the TLS, SSL, and vulnerability testing services.
Getting the payment page ready
The payment page is the page where the user will see the payment form, enter their payment details, and confirm the payment. On this page, you will need to place the widget and display the payment form.
You can configure the widget to be displayed in a pop-up window. If you select this method of displaying the widget, you don’t need to create a payment page and embed the widget into it.
Initializing the widget and displaying the payment form
Step 1. Enable the script. The library will be available in the global scope under
YooMoneyCheckoutWidget
.
Step 2. Add the HTML element that will be used as a container of the payment form. Set the 
id
attribute for this element. The minimum container width for displaying the payment form is 288 pixels.
Step 3. To initialize the widget, create a new
YooMoneyCheckoutWidget
class instance and specify the following parameters in it:
  • confirmation_token
    that you need to obtain from YooMoney before processing the payment.
  • the callback function that will receive the error code.
Specify
return_url
if you want users to get redirected to the page for finishing the payment. If you'd like to set up a custom scenario of interaction with the user, [configure how the payment process events are handled]
confirmation_token
must be obtained from YooMoney for every payment.
Step 4. To display the payment form, call the 
render
method. Send the 
id
attribute value in which you need to place the form and, if necessary, the code that must be executed after the payment form is displayed.
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. All parameters are required.
const checkout = new window.YooMoneyCheckoutWidget({
    confirmation_token: 'confirmation-token', //Token that must be obtained from YooMoney before the payment process
    return_url: 'https://example.com', //URL to the payment completion page
    error_callback: function(error) {
        //Processing of initialization errors
}
});

//Display of payment form in the container
checkout.render('payment-form')
//The method returns Promise. When Promise is executed, it means the payment form is fully loaded (optional use).
  .then(() => {
     //Code that must be executed after the payment form is displayed.
  });
</script>
Reloading the widget
If the user can cancel the order on your page, you can reload an initialized widget without reloading the entire page.
This is the process:
  1. User proceeds to payment.
  2. You send a payment creation request to YooMoney, receive a token, and display the form on the payment page.
  3. User changes something in the order.
  4. You delete the initialized widget by calling the 
    destroy
    method.
  5. You send a payment creation request to YooMoney and receive a new token.
  6. You initialize the widget with a new token and display the form on the payment page.
  7. User selects the payment method, enter their data, and confirms the payment.
  8. Widget redirects the user to the payment completion page on your side.
  9. You display the required information depending on the payment status.
Example of use of the destroy method
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. All parameters are required.
const checkout = new window.YooMoneyCheckoutWidget({
    confirmation_token: 'confirmation-token', //Token that must be obtained from YooMoney before the payment process
    return_url: 'https://example.com', //URL to the payment completion page
    error_callback: function(error) {
        //Processing of initialization errors
}
});

//Display of payment form in the container
checkout.render('payment-form')
//The method returns Promise. When Promise is executed, it means the payment form is fully loaded (optional use).
  .then(() => {
     //Code that must be executed after the payment form is displayed.
  });

//Deletion of  payment form from the container
checkout.destroy();

//Initialization of a new widget. All parameters are required.
const checkoutNew = new window.YooMoneyCheckoutWidget({
    confirmation_token: 'confirmation-token', //Token that must be obtained from YooMoney before the payment process
    return_url: 'https://example.com', //URL to the payment completion page
    error_callback: function(error) {
        //Processing of initialization errors
}
});

//Display of payment form in the container
checkoutNew.render('payment-form')
//The method returns Promise. When Promise is executed, it means the payment form is fully loaded (optional use).
  .then(() => {
     //Code that must be executed after the payment form is displayed.
  });
</script>
Payment process
To process a payment:
  1. Create a payment in YooMoney
  2. Initialize the widget
  3. Complete the payment
If you’d like to display a custom message to the user in case a payment via bank card is unsuccessful, contact your YooMoney manager.
Step 1. Create a payment
To create a payment, send a request to YooMoney, include the data for request authentication, the idempotency key, the 
amount
object containing the payment amount, the 
confirmation
object with the 
embedded
type, and if necessary the 
description
parameter with a description of the transaction that will be displayed in your Merchant Profile and returned in response to payment information  requests.
You can set any other parameters in the request, except for
payment_method_data
,
payment_method_id
,
payment_token
,
airline
. For example, you can specify the parameters for the configuration of the interface copy language or for saving the payment method for recurring payments.
cURL
PHP
Python
curl https://api.yookassa.ru/v3/payments \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "2.00",
          "currency": "RUB"
        },
        "confirmation": {
          "type": "embedded"
        },
        "capture": true,
        "description": "Order No. 72"
      }'
Step 2. Initialize the widget and display the payment form
YooMoney will return
confirmation_token
in the payment object .
JSON
{
  "id": "22d6d597-000f-5000-9000-145f6df21d6f",
  "status": "pending",
  "paid": false,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "embedded",
    "confirmation_token": "ct-24301ae5-000f-5000-9000-13f5f1c2f8e0"
  },
  "created_at": "2018-07-10T14:25:27.535Z",
  "description": "Order No. 72",
  "metadata": {},
  "recipient": {
    "account_id": "100500",
    "gateway_id": "100700"
  },
  "refundable": false,
  "test": false
}
Use this token for
YooMoneyCheckoutWidget
class instantiation and widget initialization.
The token can only be used once, it’s valid for 1 hour. If you use an expired token, the 
token_expired
error will be returned and the widget won’t be initialized. If the user pays and goes back to the same form, it’ll be displayed with an error. If the user doesn’t confirm the payment before the token expires, YooMoney will cancel the payment and you’ll need to finish the payment process (see step 3).
To request the token again, create another payment and initialize the widget using the new token.
Step 3. Complete the payment
When the user enters the payment details and confirms the payment or when the token expires, YooMoney will redirect the user to 
return_url
which you’ll specify when initializing the widget or executes the actions that you scripted for the event when the payment is finished. You will need to check the payment results (success or failure) independently and display the necessary information to the user.
You can check the payment status in a notification sent by YooMoney, or you can send periodic requests for payment information .
Done!

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