Yandex.Checkout Widget
Using the Yandex.Checkout widget, you can embed a ready-made payment form on your website. The user can pay via several payment methods, such as Yandex.Money wallet and bank cards linked to it, arbitrary bank card, Apple Pay, Google Pay, and Sberbank Online. The widget allows users to save bank cards and Yandex.Money wallets for recurring payments in your store.
Yandex.Checkout widget’s payment form
The payment form automatically adjusts to the size of the user’s device, checks the entered data and alerts the user if something is entered incorrectly. You can set up the interface language and customize the color scheme of the payment form.
To process a payment via the widget, just create a payment using the Yandex.Checkout API, initialize the widget, and display the form on the payment page.
Integration:
  1. Read about the payment processing scenario in the widget.
  2. Set up payment methods.
  3. Prepare the payment page.
  4. Implement payment processing.
  5. If necessary, set up the 3-D Secure authentication method.
  6. Implement recurring payments if necessary.
  7. If necessary, customize the widget’s color scheme.
  8. Set up the processing of widget initialization errors.
 Payment processing scenario
  1. User proceeds to payment.
  2. You send a request for creating a payment to Yandex.Checkout.
  3. Yandex.Checkout returns the created payment object with a token for initializing the widget.
  4. You initialize the widget and display the form on the payment page.
  5. User selects a payment method, enters their details.
  6. Widget redirects the user to the payment confirmation page (for example, for 3-D Secure authentication) if required.
  7. User confirms the payment.
  8. The widget redirects the user to the payment completion page on your side.
  9. You display the relevant information depending on the payment status.
Done!
 Payment method configuration
The widget supports the following payment methods:
  • Yandex.Money wallet and bank cards linked to it,
  • arbitrary bank cards,
  • Apple Pay,
  • Google Pay,
  • Sberbank Online.
Only authorized users can pay with the Yandex.Money wallet and bank cards linked to it.
 General configuration
By default, the only payment methods are Yandex.Money wallets and linked cards. Contact the Yandex.Checkout manager to find out other payment methods available to you.
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 enable Apple Pay, you’ll need perform additional configuration.
 Apple Pay configuration
Step 1. Provide your Yandex.Checkout manager with the URL of the website where you’re going to embed the widget.
Step 2. Download the merchant.ru.yandex.kassa file and upload it to your website at:
https://<your website URL>/.well-known/apple-developer-merchantid-domain-association
This is the only acceptable path to the file, including the period and hyphens. A period in the URL indicates a hidden folder.
Step 3. 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.
 Payment page
To accept payments, prepare a payment page by connecting the library and embedding the widget.
Step 1. Enable the script. The library will be available in the global scope under
YandexCheckout
.
Step 2. Add the HTML element that will be used as a container of the payment form. Set the
id
attribute for this element.
Step 3. To initialize the widget, create a new
YandexCheckout
class instance with
confirmation_token
that you need to obtain from Yandex.Checkout 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, customize the color scheme.
confirmation_token
must be obtained from Yandex.Checkout for every payment.
Step 4. To display the payment form, call the
render
method. Use the value of container’s
id
attribute as the argument.
HTML
<!--Library implementation-->
<script src="https://kassa.yandex.ru/checkout-ui/v2.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.YandexCheckout({
    confirmation_token: 'confirmation-token', //Token that must be obtained from Yandex.Checkout before the payment process
    return_url: 'https://merchant.site', //URL to the payment completion page
    error_callback(error) {
        //Processing of initialization errors
}
});

//Display of payment form in the container
checkout.render('payment-form');
</script>
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.
 Payment process
To process a payment:
  1. Create a payment in Yandex.Checkout
  2. Initialize the widget
  3. Complete the payment
If you want to test the widget, create a payment for your demo store and pay with one of the test cards. More about payment testing
 Step 1. Create a payment
To create a payment, send a request to Yandex.Checkout, 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 to the user during the payment process. Also include the
capture
parameter with the
true
value. This means you will receive the money immediately after the payment (if the value is 
false
, the required amount will be held on the user’s account, and you’ll be able to capture it whenever convenient).
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
.
You can set any other parameters in the request, except for
payment_method_data
,
payment_method_id
,
payment_token
,
airline
.
cURL
PHP
Python
curl https://payment.yandex.net/api/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
Yandex.Checkout 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
YandexCheckout
class instantiation and widget initialization.
The token is for single-use only. If not used, the token will expire after 1 hour. If the user does not pay within an hour, the widget will not be initialized, and you will need to request the token again. If the user pays and returns to the form, it will be displayed with an error.
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, Yandex.Checkout will redirect them to 
return_url
which you specify during widget initialization. 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 Yandex.Checkout, or you can send periodic requests for payment information .
 Saving payment methods for recurring payments
Using the Yandex.Checkout widget, you can save payment methods and use them for recurring payments, for example, as a monthly charge for a subscription.
Recurring payments are only enabled by default in the demo store. If you want to enable them in your real store, contact the Yandex.Checkout manager.
If you’re allowed to use autopayments, you can process payments:
 Payment with the payment method saved
By saving the payment method, you can save a bank card or Yandex.Money wallet in your store. Using the widget, you can process payments and save the payment method unconditionally or conditionally.
Payment method is saved unconditionally when the method is saved by default and the user can’t affect this. The process is as follows:
  1. On your website, you place the warning for the user alerting them that you will save their payment details and explaining how you will use it (for example, the frequency and amounts of your future debits) and how the user can disable recurring charges in your store. On your side, you receive the user’s consent to make autopayments.
  2. The widget displays only two payment methods to the user: with an arbitrary bank card or from a Yandex.Money wallet (if the user is logged in to their Yandex account). After the user selects the payment method, the widget will inform them that the payment method will be in to your store. Upon successful payment, the bank card or wallet details will be automatically saved in Yandex.Checkout.
Example of usage: subscription for regular payments.
Payment with the payment method saved unconditionally
Payment method is saved conditionally when the method is saved by the user’s request. The process is as follows:
  1. On your website, you let the user know that they can save their payment details and explain how you will use it and how the user can disable the option.
  2. The widget displays all available payment methods to the user. If the user selects payment with an arbitrary bank card or Yandex.Money wallet, the widget will offer them to save payment details in your store. If the user agrees and the payment is processed successfully, the payment method information will be saved in Yandex.Checkout, and you will be able to use the saved payment method’s ID for recurring payments. If the user refuses, the information will not be saved in the store after the payment.
Example of usage: saving a means of payment in the store to speed up the payment process for subsequent payments.
Payment with the payment method saved conditionally
 Payment with the payment method saved unconditionally
Step 1. Create a payment and specify
save_payment_method
parameter with the
true
value.
cURL
PHP
Python
curl https://payment.yandex.net/api/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,
        "save_payment_method": true,
        "description": "Order No. 72"
      }'
Step 2. Yandex.Checkout will respond with
confirmation_token
, the token for initializing the widget.
JSON
{
  "id": "25564507-000f-5000-9000-19878c91d156",
  "status": "pending",
  "paid": false,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "embedded",
    "confirmation_token": "ct-25564507-000f-5000-9000-19878c91d156"
  },
  "created_at": "2019-11-07T14:59:19.351Z",
  "description": "Order No. 72",
  "metadata": {},
  "recipient": {
    "account_id": "100001",
    "gateway_id": "1000001"
  },
  "refundable": false,
  "test": false
}
Step 4. Process the payment in the usual manner.
If the payment is processed successfully, you will receive the saved payment method’s ID.
 Payment with the payment method saved conditionally
Step 1. Create a payment (no need to include
save_payment_method
).
cURL
PHP
Python
curl https://payment.yandex.net/api/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. Yandex.Checkout will respond with
confirmation_token
, the token for initializing the widget.
JSON
{
  "id": "25564507-000f-5000-9000-19878c91d156",
  "status": "pending",
  "paid": false,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "embedded",
    "confirmation_token": "ct-2557c659-000f-5000-9000-12714806d854"
  },
  "created_at": "2019-11-07T14:59:19.351Z",
  "description": "Order No. 72",
  "metadata": {},
  "recipient": {
    "account_id": "100001",
    "gateway_id": "1000001"
  },
  "refundable": false,
  "test": false
}
Step 4. Process the payment in the usual manner.
If the payment is processed successfully, you will receive the saved payment method’s ID.
 Getting the saved payment method’s ID
Step 1. Wait until the user confirms the payment, and its status changes to 
succeeded
(or 
waiting_for_capture
if it’s a two-stage payment). You can check the payment status in a notification sent by Yandex.Checkout, or you can send periodic requests for payment information .
Step 2. Make sure the payment method is saved: the
payment_method.saved
value in the payment object has changed to 
true
.
JSON
{
  "id": "25564507-000f-5000-9000-19878c91d156",
  "status": "succeeded",
  "paid": true,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "authorization_details": {
    "rrn": "10000000000",
    "auth_code": "000000"
  },
  "captured_at": "2018-07-18T17:20:50.825Z",
  "created_at": "2018-07-18T17:18:39.345Z",
  "description": "Order No. 72",
  "metadata": {},
  "payment_method": {
    "type": "bank_card",
    "id": "25564507-000f-5000-9000-19878c91d156",
    "saved": true,
    "card": {
      "first6": "555555",
      "last4": "4444",
      "expiry_month": "07",
      "expiry_year": "2022",
      "card_type": "MasterCard",
      "issuer_country": "RU",
      "issuer_name": "Sberbank"
    },
    "title": "Bank card *4444"
  },
  "refundable": true,
  "refunded_amount": {
    "value": "0.00",
    "currency": "RUB"
  },
  "recipient": {
    "account_id": "100001",
    "gateway_id": "1000001"
  },
  "test": false
}
Step 3. Save the
payment_method.id
. You’ll need to use it as the identifier of the saved payment method for subsequent payments.
Done!
Now you can make recurring payments. You’ll need to implement payments with a saved payment method independently.
 Payments without saving the payment method
You can process payments without saving the payment method. The user can pay via any available payment methods. The method won’t be saved.
To process a payment without saving the payment method:
Step 1. Create a payment and specify the
save_payment_method
parameter with the
false
value.
cURL
PHP
Python
curl https://payment.yandex.net/api/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,
        "save_payment_method": false,
        "description": "Order No. 72"
      }'
Step 2. Yandex.Checkout will respond with
confirmation_token
, the token for initializing the widget.
JSON
{
  "id": "25564507-000f-5000-9000-19878c91d156",
  "status": "pending",
  "paid": false,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "embedded",
    "confirmation_token": "ct-25564507-000f-5000-9000-19878c91d156"
  },
  "created_at": "2019-11-07T14:59:19.351Z",
  "description": "Order No. 72",
  "metadata": {},
  "recipient": {
    "account_id": "100001",
    "gateway_id": "1000001"
  },
  "refundable": false,
  "test": false
}
Step 4. Process the payment in the usual manner.
 Authentication via 3-D Secure for bank card payments
When paying with a bank card, the user usually needs to confirm the payment by passing the 3-D Secure authentication. To do that, the user enters a special text message code on the issuer’s page. If everything is in order, the payment is successful, if not, the payment is canceled.
The widget allows you to control where the confirmation process will take place: on a separate page or in a pop-up window.
Authentication on a separate page (used by default): the user leaves your website for authentication, meaning the widget redirects them from the payment page to the issuer’s page. After the verification, the issuer redirects the user to the payment completion page on your side.
Example of authentication on a separate page
Authentication in pop-up window: the user is authenticated without leaving your website, as the widget on the checkout page displays a pop-up with the issuer’s page. After the verification, the issuer redirects the user to the payment completion page on your side.
Example of authentication in a pop-up window
To set up the 3-D Secure authentication:
 General authentication scenario
The authentication process for bank card payments is as follows:
  1. User enter their bank card details in the widget’s payment form, then clicks Pay.
  2. Widget redirects the user to the issuer’s page or displays a pop-up window.
  3. User completes verification.
  4. Issuer provides Yandex.Checkout with the authentication results.
  5. Issuer redirects the user to the payment completion page, i.e. the
    return_url
    that you specified during widget initialization.
  6. You get the authentication results from Yandex.Checkout, then display them to the user.
The user can interrupt the authentication process if, for example, they close the page or the pop-up window. If, after that, they’ll decide to return to the payment page, create the payment again, get a token, and initialize the widget. The old token will be invalid, and the payment linked to it will stay in the
pending
status until the token expires, then the status will automatically change to 
canceled
.
If the user fails authentication (enters the incorrect code), the payment will be cancelled (with the status changing to 
canceled
) and the 3-D Secure authentication failure will be listed as the cancellation reason.
 Authentication settings
Select a 3-D Secure authentication method:
 Authentication on a separate page
This is the default authentication method in the widget.
Send the
embedded_3ds
parameter with the
false
value during widget initialization so the user will complete 3-D Secure authentication on a separate page.
HTML
<!--Library implementation-->
<script src="https://kassa.yandex.ru/checkout-ui/v2.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.YandexCheckout({
    confirmation_token: 'confirmation-token', //Token that must be obtained from Yandex.Checkout before the payment process
    return_url: 'https://merchant.site', //URL to the payment completion page
    embedded_3ds: false, // 3-D Secure authentication on a separate page.
    error_callback(error) {
        //Processing of initialization errors
}
});

//Display of payment form in the container
checkout.render('payment-form');
</script>
If you don’t specify the
embedded_3ds
method, the user will also complete authentication on a separate page.
If the user leaves the issuer’s page during the authentication process by, for example, closing it or returning to the payment page, the payment will be interrupted. If the user wants to resume the payment process, create the payment again, initialize the widget, and display the payment form.
 Authentication in a pop-up window
Send the
embedded_3ds
parameter with the
true
value during widget initialization so the user will complete 3-D Secure authentication in a pop-up window.
HTML
<!--Library implementation-->
<script src="https://kassa.yandex.ru/checkout-ui/v2.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.YandexCheckout({
    confirmation_token: 'confirmation-token', //Token that must be obtained from Yandex.Checkout before the payment process
    return_url: 'https://merchant.site', //URL to the payment completion page
    embedded_3ds: true, // 3-D Secure authentication in a pop-up window
    error_callback(error) {
        //Processing of initialization errors
}
});

//Display of payment form in the container
checkout.render('payment-form');
</script>
Pop-up window measurements:
  • maximum width is 600 pixels,
  • maximum height is 800 pixels.
On mobile devices, the pop-up window takes up the entire screen.
If the user closes the pop-up or leaves the checkout page, the payment will be interrupted. If the user tries to close the pop-up window, the widget will display a warning that the payment will be interrupted and the user will have to start over. If the user confirms the action, the pop-up window will close and a notification will appear on the payment page instead of the payment form that the process has been interrupted.
Notification on the payment page after the pop-up window is closed
If the user wants to return to the payment process, create the payment again, initialize the widget, and display the payment form.
Add the UTF-8 coding support to your website, so that all the messages are displayed correctly.
 Authentication testing
Recommendations for checking the 3-D Secure authentication:
  1. Test the successful scenario.
  2. Test the unsuccessful scenario (user fails authentication).
  3. Test payment interruption during authentication by leaving or closing the issuer’s page, closing the pop-up window, and the payment page.
You can test successful and unsuccessful scenarios with test bank cards (these cards only work in your demo store).
 Configure 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://kassa.yandex.ru/checkout-ui/v2.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.YandexCheckout({
    confirmation_token: 'confirmation-token', //Token that must be obtained from Yandex.Checkout before the payment process
    return_url: 'https://merchant.site', //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(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://kassa.yandex.ru/checkout-ui/v2.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.YandexCheckout({
    confirmation_token: 'confirmation-token', //Token that must be obtained from Yandex.Checkout before the payment process
    return_url: 'https://merchant.site', //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(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
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 (Yandex.Money wallet, bank card, Sberbank Online), Apple Pay and Google Pay buttons, the Pay button, an offer acceptance message, and the Yandex.Checkout 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
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 Yandex.Money and Yandex.Checkout logos 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)
 Reference for color scheme configuration parameters
Description of all parameters in the
colors
object that can be used for configuring the color scheme.
ParameterDescriptionDefault
controlPrimaryBackground color for accent elements: the Pay button, selected radio buttons, checkboxes, border of the selected text field. We recommend using a bright color to draw attention
#FFCC00
(yellow)
controlPrimaryContentColor of the text in the Pay button and the contents of accent radio buttons and checkboxes (for example, a ticked checkbox). We recommend using a color that will contrast with
controlPrimary
.
If the parameter is not specified, the color will be determined on the basis of 
controlPrimary
#000000
(black) или
#FFFFFF
(white) — selected to contrast with
controlPrimary
backgroundPayment form background color, color of error messages and tips, appearance of the Apple Pay and Google Pay buttons and logos. We recommend using a color close to the background color of the container where the widget is placed
#FFFFFF
(white)
textColor of all texts on the payment form except for the text in the Pay button and tooltips.
If the parameter is not specified, the color is determined on the basis of 
background
Contrast to 
background
borderColor of borders and separators.
If the parameter is not specified, the color is determined on the basis of 
background
Contrast to 
background
controlSecondaryColor of non-accent interface elements.
If the parameter is not specified, the color is determined on the basis of 
background
Contrast to 
background
 New payment form design
Starting from 23 September 2020, a new payment form design is available for the widget.
Payments via the new widget
At the moment, the widget supports both design options: old and new, so that you could get ready for the changes using the option that’s more convenient for you.
In order for the payment form to be displayed in the new design, send the
newDesign
parameter with
true
as its value.
This is a temporary parameter. Eventually, only the new design option will remain, and the
newDesign
parameter won’t have any influence on what the payment form looks like.
HTML
<!--Library implementation-->
<script src="https://kassa.yandex.ru/checkout-ui/v2.js"></script>

<!--HTML element in which the payment form will be displayed-->
<div id="payment-form"></div>

<script>
//Widget initialization. All parameters except newDesign are required
const checkout = new window.YandexCheckout({
    confirmation_token: 'confirmation-token', //Token that must be obtained from Yandex.Checkout before the payment process
    return_url: 'https://merchant.site', //URL to the payment completion page
    newDesign: true, // Display the payment form in the new design
    error_callback(error) {
        //Processing of initialization errors
    }
});

//Display of payment form in the container
checkout.render('payment-form');
</script>
If you’ve customized the color scheme, the payment form will be displayed in your custom colors in the new design. No additional configuration for the new design is required.
Examples of color scheme configuration for the new payment form design
 Reference for parameters and error codes
Description of parameters sent during widget initialization and the description of errors related to initialization.
 Reference of parameters for widget initialization
Description of parameters that must be sent to the instance of the
YandexCheckout
class on the payment page for widget initialization.
ParameterTypeMandatoryDescription
confirmation_tokenstringRequiredYandex.Checkout token for initializing the widget. To issue a token, create a payment
return_urlstringRequiredAddress of the page for redirecting the user after the payment is completed. The address must be absolute (with the protocol and website domain specified). Example:
https://merchant-web-site.com/orderid-1111
3ds_embeddedbooleanOptional3-D Secure authentication method:
true
— pop-up window,
false
— separate page.
Default value:
false
customizationobjectOptionalPayment form customization. Right now, only color scheme customization is available
colorsobjectOptionalSent in 
customization
.
Color scheme customiaztion. List of parameters that can be sent in colors
newDesignbooleanOptionalPayment form design option selection:
true
new design,
false
— old design.
This is a temporary parameter. Eventually, only the new design option will remain, and the
newDesign
parameter won’t have any influence on what the payment form looks like.
 Widget initialization errors
If the widget initialization failed, Yandex.Checkout will send an error code to the callback function.
Error codeValue
internal_service_error
Error during payment creation. Repeat widget initialization
invalid_return_url
Invalid return URL. During widget initialization, specify the absolute URL of the payment completion page in 
return_url
with the protocol and domain of your website
invalid_token
Invalid token. Create a payment to obtain a token
return_url_required
Return URL not specified. Specify
return_url
during widget initialization
token_expired
Token has expired. Create a payment to obtain a new token
token_required
Token not sent. Send
confirmation_token
during widget initialization
 See also
Quick startPayment processNotificationsRecurring payments