Web SDK guide

Yandex Pay Web SDK enables you to connect the order and checkout forms for your online store.

Requirements for connecting

To install the Yandex Pay button, make sure your site meets the requirements:

  • The site works over the HTTPS protocol.

  • The site doesn't cut out the __YP__ parameter from the URL (learn more here).

  • Your site's CSP policies allow using:

    script-src: https://pay.yandex.ru
    frame-src: https://pay.yandex.ru
    img-src: https://pay.yandex.ru
    connect-src: https://pay.yandex.ru
    style-src: 'unsafe-inline'
    
  • Your site doesn't use the headers:

    Cross-Origin-Opener-Policy: *
    

Connect Yandex Pay

Diagnostics and debugging

To run diagnostics on your connection to Yandex Pay at the debugging stage, use the browser's developer console.

On the Yandex Pay form page, click Command + Option + I, and go to the Console tab.

On the Yandex Pay form page, click F12 or Control + Shift + I, then click Console.

Step 1. Adding the SDK to the page

Add the HTML code to all pages where you put the Yandex Pay button before the closing </body> tag. Pass the name of the method for initializing and processing payments to the onload attribute.

<script src="https://pay.yandex.ru/sdk/v1/pay.js" onload="onYaPayLoad()" async></script>

Step 2. Creating the order/payment form

You can add payment form.

In the payment form, the customer can pay for a previously created order by:

  • Select a payment method.
  • Pay for the order.
function onYaPayLoad() {
    const YaPay = window.YaPay;

    // Payment details
    const paymentData = {
        // For debugging, you need to explicitly specify the `SANDBOX` environment.
        // For the production environment, you can omit this parameter or specify `PRODUCTION`.
        env: YaPay.PaymentEnv.Sandbox,

        // Version 2 points at paying via Yandex Pay
        // The user pays in the Yandex Pay form,
        // and only the result of the payment transfer is returned to the merchant
        version: 3,

        // Code of the currency in which you are going to accept payments
        currencyCode: YaPay.CurrencyCode.Rub,

        // Merchant ID received on registration in Yandex Pay
        merchantId: '<YOUR_MERCHANT_ID>',


        // IMPORTANT!
        // Paid order ID
        // If it's available, the payment form is shown
        //               rather than the checkout form
        orderId: 'order-id',

        // Details of the customer's cart (optional)
        cart: {
            // Items in the cart
            items: [
                {
                    productId: '1',
                    total: '26990.00',
                },
                {
                    productId: '3',
                    // If needed, specify the number of items
                    quantity: { count: 2 },
                    // Total for two items is (7990 * 2)
                    total: '15980.00',
                },
            ],
        },

        // Arbitrary additional data for the cart (optional)
        // After applying encodeURIComponent, the data couldn't be longer than 128 characters
        metadata: 'order-metadata',
    };

    // Payment success handler
    function onPaymentSuccess(event) {
        // Order placed successfully
        // show the order success screen to the user
        console.log(`OrderId — ${event.orderId}\nMetadata — ${event.metadata}`);
    }

    // Payment error handler
    function onPaymentError(event) {
        // Show a message that the payment method is unavailable at the moment
        // and suggest the user to try another method.
        console.log(`Payment error — ${event.reason}`);
    }

    // Payment cancellation handler
    function onPaymentAbort(event) {
        // The user closed the Yandex Pay form.
        // Suggest the user to try another payment method.
    }

    // Create a payment session
    YaPay.createSession(paymentData, {
        onSuccess: onPaymentSuccess,
        onAbort: onPaymentAbort,
        onError: onPaymentError,
    })
        .then(function (paymentSession) {
            // Show the Yandex Pay button on the page.
            paymentSession.mountButton(document.querySelector('#button_container'), {
                type: YaPay.ButtonType.Pay,
                theme: YaPay.ButtonTheme.Black,
                width: YaPay.ButtonWidth.Auto,
            });
        })
        .catch(function (err) {
            // Couldn't create a payment session.
        });
}

Examples of working with the Web SDK

Embedded components

  1. Yandex Pay payment buttons
  2. Yandex Pay payment widgets.

Operations with the payment

  1. Updating the cart.
  2. Recreating the payment session and Yandex Pay buttons.
  3. Passing discount coupons.

Specifics

  1. How Yandex Pay transfers payments via redirect queries.

Yandex Pay integration on the server side

To learn more about setting up integration on the server, see Backend integration.