YooMoney Checkout Widget: Integration — Payment acceptance via the YooMoney API

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 method	Availability
YooMoney	Available by default
Bank card	Available if the store is allowed to accept payments using this method.
Mir Pay	Available if the store is allowed to accept payments using this method. The button is displayed for payments on mobile devices on Android.
Tinkoff Pay	Available if the store is allowed to accept payments using this method.
SberPay	Available 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.
“Credit purchases“ by SberBank	Available if the store is allowed to accept payments using this method. Two option types are available: loans and installment plans. The payment form only displays the payment plans that you have enabled.

Website requirements

The widget can display various messages to the user during the payment process. In order for the user to be able to read them, your website must use the UTF-8 encoding.

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.

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:

User proceeds to payment.
You send a payment creation request to YooMoney, receive a token, and display the form on the payment page.
User changes something in the order.
You delete the initialized widget by calling the destroy method.
You send a payment creation request to YooMoney and receive a new token.
You initialize the widget with a new token and display the form on the payment page.
User selects the payment method, enter their data, and confirms the payment.
Widget redirects the user to the payment completion page on your side.
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();

//Инициализация нового виджета. Все параметры обязательные.
const checkoutNew = new window.YooMoneyCheckoutWidget({
    confirmation_token: 'confirmation-token', //Токен, который перед проведением оплаты нужно получить от Яндекс.Кассы
    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:

Create a payment in YooMoney
Initialize the widget
Complete the payment

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!