YooMoney Checkout Widget: Payment form design — Payment acceptance via the YooMoney API

Payment form design

In the widget's payment form, you can change the language of the copy or configure the colors of interface elements.

Language configuration

By default, the payment form copy is displayed in Russian. To change the interface language to English, specify the locale parameter with en_US value in confirmation when creating a payment.

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",
          "locale": "en_US"
        },
        "capture": true,
        "description": "Order No. 72"
      }'

Configuring the interface color scheme

By default, the widget has a white payment form, while important elements, such as the Pay button, are accentuated yellow. These design choices help the user to focus on the main things: which payment method to choose, where to enter the data, and how to proceed to the payment.

The widget can be adapted to any design. To customize it, all you need is one or two colors, and the rest will be selected by the widget itself. If necessary, you can correct the automatically selected colors by sending additional parameters.

Examples of customized color schemes

Color scheme customization

The color scheme is set during widget initialization using the colors object sent in the customization object. The colors object specifies parameters that affect the colors of interface elements.

A maximum of six parameters can be set: two basic and four additional. Each of the basic parameters is responsible for a specific group of interface elements. If you send such a parameter, the widget will use it as the basis for determining all the other colors. If necessary, you can refine the automatically matched colors using additional options.

Color values must be specified in hexadecimal notation (HEX), otherwise the widget will ignore the settings.

Articles that might help in customizing the color scheme:

Quick start

Select what you want to change: the Pay button color or the color of the form.

Quick start: Pay button

Step 1. Add the customization object with the colors object and the control_primary parameter to the script for widget initialization.

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 except for the customization object.
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

    //Widget customization
    customization: {
        //Color scheme customization, minimum one parameter, color values in HEX
        colors: {
            //Accent color: Pay button, selected radio buttons, checkboxes, and text boxes
            control_primary: '#00BF96' //Color value in HEX
        }
    },
    error_callback: function(error) {
        //Processing of initialization errors
    }
});

//Display of payment form in the container
checkout.render('payment-form');
</script>

Step 2. Create a payment for the demo store and initialize the widget.

Example of setting from Quick start (Pay button)

Done! The Pay button and other accent elements changed their color.

This is the easiest way to change the color of accent elements. You can select another customization option if you want to refine the automatically determined colors or change other interface elements.

Quick start: entire payment form

Step 1. Add the customization object with the colors object and the control_primary and background parameters to the script for widget initialization.

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 except for the customization object.
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

    //Widget customization
    customization: {
        //Color scheme customization, minimum one parameter, color values in HEX
        colors: {
            //Accent color: Pay button, selected radio buttons, checkboxes, and text boxes
            control_primary: '#00BF96', //Color value in HEX

            //Color of the payment form and its elements
            background: '#F2F3F5' //Color value in HEX
        }
    },
    error_callback: function(error) {
        //Processing of initialization errors
    }
});

//Display of payment form in the container
checkout.render('payment-form');
</script>

Step 2. Create a payment for the demo store and initialize the widget.

Example of setting from Quick start (entire payment form)

Done! Payment form and the Pay button have changed their colors.

This is the easiest way to change the colors of the entire payment form. You can select another customization option if you want to refine the automatically determined colors or change other interface elements.

Color scheme customization options

Number of parameters sent in colors depends on what you want to change:

Accent elements only: white payment form suits your website but the yellow accent elements don’t.
Payment form only: yellow accents are good but you want to change the form’s color (for example, your website uses a dark theme).
Accent elements and payment form: default color scheme doesn’t suit the website, all elements need to be recolored.
Details only: the design generally suits you but some details need to be changed, for example, color of the payment form borders.

All parameters of the colors object

Customization options: accent elements only

Accent elements in the widget help the user to focus and call to action: Pay button, selected radio buttons, checkboxes, border of the selected text box.

Two parameters affect the color of accent elements:

control_primary (base color) — color of the Pay button and other accent elements.
control_primary_content — color of the text in the button and the contents of accent radio buttons and checkboxes (for example, ticked checkbox).

To change the color of accent elements, you only need to send control_primary. In this case, the widget will automatically select either black or white as the text color (whichever one is more contrasting to control_primary).

Parameters determining the color of accent elements: payment method selection screen

Parameters determining the color of accent elements: data entry screen

For control_primary, it’s preferable to use an attention-grabbing color, for control_primary_content, a contrasting color that will be easy to read against the base color.

We recommend starting the configuration with the base color, then use the additional color if necessary:

Step 1. Add the customization object with the colors object and the control_primary parameter to the script for widget initialization.

JavaScript
    customization: {
        //Color scheme customization, minimum one parameter, color values in HEX
        colors: {
          control_primary: '#00BF96' // Base color of the Pay button and other accent elements
          // Text color in the Pay button, icon color in checkbox or radio button will be selected automatically
        }
    },

Step 2. Create a payment for the demo store, initialize the widget, and take a look at the payment form’s design.

Step 3. If necessary, retouch the automatically selected text color of the Pay button. To do that, add the control_primary_content parameter with the required color to the script and re-initialize the widget (or refresh the payment page).

JavaScript
    customization: {
        //Color scheme customization, minimum one parameter, color values in HEX
        colors: {
          control_primary: '#00BF96', // Base color of the Pay button and other accent elements
          control_primary_content: '#FFFFFF' // Text color in the Pay button, icon color in radio button and checkbox
        }
    },

Example of accent element color configuration (control_primary and control_primary_content)

Done! You can use the widget to accept payments from your customers.

Return to selecting the configuration options

Customization options: payment form only

The payment form consists of payment method blocks (YooMoney wallet, bank card, SberPay, Mir Pay, and other methods), an offer acceptance message, and the YooMoney logo.

The background color that the elements are placed against is the color of the payment page or the background of the container where the widget is located (you change it yourself on the payment page). The Pay button is an accent element that can be configured separately. All other elements are affected by four parameters:

background (base color) — background color of payment method blocks, color of error messages and tips.
text — text color.
border — color of borders and separators.
control_secondary — color of non-accent interface elements.

To change the color of the payment form, you only need to send background. In this case, the widget will determine the color of borders, text, and non-accent elements automatically.

Parameters determining the form color: payment method selection screen

Parameters determining the form color: data entry screen

For background, it’s preferable to use a color that’s close to the container’s background color, for text, a contrasting color that will be easy to read against the payment form, non-accent elements, and the container. We recommend selecting other colors to match the one selected for background.

We recommend starting the configuration with the base color, then use the additional colors if necessary:

Step 1. Add the customization object with the colors object and the background parameter to the script for widget initialization.

JavaScript
    customization: {
        //Color scheme customization, minimum one parameter, color values in HEX
        colors: {
          background: '#F2F3F5' // Payment form background color
          //Color of the text, borders, non-accent elements will be determined automatically
        }
    },

Step 2. Create a payment for the demo store, initialize the widget, and take a look at the payment form’s design.

Step 3. If necessary, retouch the color automatically selected for the text, borers, and non-accent elements. To do that, add the additional parameters with the required colors to the script and re-initialize the widget (or refresh the payment page).

JavaScript
    customization: {
        //Color scheme customization, minimum one parameter, color values in HEX
        colors: {
          background: '#F2F3F5', // Payment form background color
          text: '#222222', // Text color
          border: '#D4D4D4', // Color of borders and separators
          control_secondary: '#AFBDCA' // Color of non-accent interface
        }
    },

Example of payment form color configuration (background, text, border, control_secondary)

Done! You can use the widget to accept payments from your customers.

Return to selecting the configuration options

Customization options: accent elements and payment form

If you want to change all colors of the widget, use the options for changing both the accent elements and the payment form.

We recommend starting the configuration with base colors, then use the additional colors if necessary:

Step 1. Add the customization object with the colors object and the control_primary and background parameters to the script for widget initialization.

JavaScript
    customization: {
        //Color scheme customization, minimum one parameter, color values in HEX
        colors: {
          background: '#0D182F',  // Payment form background color
          control_primary: '#00BF96' // Color of the Pay button and other accent elements
        }
    },

Step 2. Create a payment for the demo store, initialize the widget, and take a look at the payment form’s design.

Step 3. If necessary, retouch the automatically selected color. To do that, add the additional parameters with the required colors to the script and re-initialize the widget (or refresh the payment page).

JavaScript
    customization: {
        //Color scheme customization, minimum one parameter, color values in HEX
        colors: {
          background: '#0D182F', // Payment form background color
          control_primary: '#00BF96', // Color of the Pay button and other accent elements
          control_primary_content: '#FFFFFF', // Color of the Pay button
          control_secondary: '#366093', // Color of non-accent interface elements
          border: '#244166', // Color of borders and separators
          text: '#DBDCE0' // Text color
        }
    },

Example of configuring all colors (all parameters). Container background is specified separately

Done! You can use the widget to accept payments from your customers.

Return to selecting the configuration options

Customization options: details only

You can set just the additional colors, for example, only the color of the border. If you need to change the base colors, use the instructions for customizing the accent elements and the payment form.

Recommended customization order:

Step 1. Add the customization object with the colors object and the required parameters to the script for widget initialization.

Step 2. Create a payment for the demo store, initialize the widget, and take a look at the payment form’s design.

Done! You can use the widget to accept payments from your customers.

Example of selective color customization

JavaScript
    customization: {
        //Color scheme customization, minimum one parameter, color values in HEX
        colors: {
          control_primary_content: '#0070F0', // Color of the Pay button
          border: '#00BF96' // Color of borders and separators
        }
    },

Example of selective color customization (control_primary_content and border)

Return to selecting the configuration options