Widget integration
Detailed guide to using the YooMoney widget for payment acceptance.
 
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
Apple Pay
Available if the store is allowed to accept payments using this method. You will need to additionally configure your website and specify the settings in the Merchant Profile.
After the implementation, the payment button will only be displayed on the payment form if the user opens the page with the widget in the Safari browser and signs in to their Apple account.
By implementing Apple Pay into the widget, you agree with the terms and conditions of the Apple Pay payment service
Google PayAvailable if the store is allowed to accept payments using this method. You will need to additionally configure your website
SberBank Online or SberPayAvailable if the store is allowed to accept payments using this method. You can only use SberPay or SberBank Online. More about payments via SberBank
 
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.
If you want the widget to support payments via Google Pay and Apple Pay, your website must use HTTPS and a valid TLS/SSL certificate (minimum version is TLS v1.2). To ensure that payment using Apple Pay is always available via the widget, renew the TLS/SSL certificate no later than 8 days before its expiration date.
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.
 
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 280 pixels.
Step 3. To initialize the widget, create a new
YooMoneyCheckoutWidget
class instance with
confirmation_token
that you need to obtain from YooMoney before payment,
return_url
for sending the user after the payment, and
error_callback
as the error handler function that will be called with the error code. If necessary, you can customize the color scheme of the payment form and display options for payment methods.
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 decide on your own what message to display to the user if 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": "100001",
    "gateway_id": "1000001"
  },
  "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. 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
Payment processNotificationsReference for widget