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 or German, specify the 
locale
parameter with
en_US
or 
de_DE
value correspondingly 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 
controlPrimary
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 configuration
    customization: {
        //Color scheme customization, minimum one parameter, color values in HEX
        colors: {
            //Accent color: Pay button, selected radio buttons, checkboxes, and text boxes
            controlPrimary: '#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 
controlPrimary
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 configuration
    customization: {
        //Color scheme customization, minimum one parameter, color values in HEX
        colors: {
            //Accent color: Pay button, selected radio buttons, checkboxes, and text boxes
            controlPrimary: '#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.
 
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:
  • controlPrimary
    (base color) — color of the Pay button and other accent elements.
  • controlPrimaryContent
    — 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
controlPrimary
. In this case, the widget will automatically select either black or white as the text color (whichever one is more contrasting to 
controlPrimary
).
Parameters determining the color of accent elements: payment method selection screen
Parameters determining the color of accent elements: data entry screen
For
controlPrimary
, it’s preferable to use an attention-grabbing color, for
controlPrimaryContent
, 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 
controlPrimary
parameter to the script for widget initialization.
JavaScript
    customization: {
        //Color scheme customization, minimum one parameter, color values in HEX
        colors: {
            controlPrimary: '#00BF96' // 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 
controlPrimaryContent
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: {
            controlPrimary: '#00BF96', // Base color of the Pay button and other accent elements.
            controlPrimaryContent: '#FFFFFF' // Text color in the Pay button, icon color in radio button and checkbox
        }
    },
Example of accent element color configuration (controlPrimary and controlPrimaryContent)
Done! You can use the widget to accept payments from your customers.
 
Customization options: payment form only
The payment form consists of payment method blocks (YooMoney wallet, bank card, Sberbank Online), Apple Pay and Google Pay buttons, 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, appearance of Apple Pay and Google Pay buttons as well as logos.
  • text
    — text color.
  • border
    — color of borders and separators.
  • controlSecondary
    — 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
.
The Apple Pay and Google Pay buttons as well as the YooMoney logo can only be black or white. Their appearance depends on the 
background
parameter. Other parameters do not affect them.
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
            controlSecondary: '#AFBDCA' // Color of non-accent interface elements
        }
    },
Example of payment form color configuration (background, text, border, controlSecondary)
Done! You can use the widget to accept payments from your customers.
 
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 
controlPrimary
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
            controlPrimary: '#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
            controlPrimary: '#00BF96', // Color of the Pay button and other accent elements
            controlPrimaryContent: '#FFFFFF', // Color of the Pay button
            controlSecondary: '#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.
 
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: {
            controlPrimaryContent: '#0070F0', // Color of the Pay button
            border: '#00BF96' // Color of borders and separators
        }
    },
Example of selective color customization (controlPrimaryContent and border)

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
Checkout.jsReference for widget