Implementing a payout widget

This article describes how to use a payout widget to embed a ready-made form for obtaining bank card details on your website.

Preparing for integration

To integrate, you need a page where you will initialize a widget and display a data collection form. Once you have bank card details, you need to provide the user with results. You can do this by displaying them in place of a widget or redirect the user to a separate page.

To initialize the widget, you need your gateway ID which balance will be used to make payouts to bank cards. The ID can be found in the Merchant Profile under the Payout settings section (agentId field).

Widget integration

To get bank card information:

Set up widget initialization and displaying of the data collection form.
Set up the processing of results.
If necessary, set up the deletion of callback functions (for example, if you use single-page apps).

Initializing a widget and displaying a form

Step 1. Enable the script. The library will be available in the global scope under the PayoutsDataname.

HTML
<!--Library implementation-->
<script src="https://yookassa.ru/payouts-data/3.1.0/widget.js"></script>

Step 2. On the card data collection page, add the HTML element where the form should be placed. Set the id attribute for this element.

Step 3. To initialize the widget, create a new PayoutsData class instance and specify the following parameters in it:

type with the payout value;
account_id with the gateway ID;
success_callback that will accept card parameters;
error_callbackthat will accept the error code.

If necessary, set parameters for text language configuration and for interface color scheme customization.

Step 4. To display the form for entering the card number, call the render method. Add the value of the id attribute where the form should be placed and, if necessary, the code that should be run after the form is displayed to this method.

HTML
<!--HTML element where the form for entering the card number will be placed-->
<div id="payout-form"></div>

<script>
//Widget initialization. All parameters are required.
const payoutsData = new window.PayoutsData({
  type: 'payout',
  account_id: '<Идентификатор_шлюза>', //Идентификатор шлюза (agentId в личном кабинете)
  success_callback: function(data) {
    //Processing the response with card’s token
  },
  error_callback: function(error) {
    //Processing of errors during card token issuance
  }
});

//Отображение формы в контейнере
payoutsData.render('payout-form')
//Метод возвращает Promise, исполнение которого говорит о полной загрузке формы сбора данных (можно не использовать).
  .then(() => {
    //Код, который нужно выполнить после отображения формы.
  });
</script>

If something goes wrong during widget initialization, the errors will be displayed in the browser's console.

Processing the result

After the user sends the card number via the form, the library will return the results of the data processing as a callback function:

success_callback in case of success;
error_callback in case of error.

In case of success

If the data is processed successfully, the library will return the following parameters via success_callback:

For processing a payout: a bank card synonym (payout_token parameter).
To display information about the bank card in the interface: the first six and the last four digits of the card number, name and country of the card issuer, and card type (first6, last4, issuer_name, issuer_country, and card_type parameters respectively).

See a reference for widget to find a description of the returned parameters.

Save this information. Display the necessary information depending on your scenario to the user.

In case of error

If there was an error during the processing of data, the library will return the error code via error_callback.

Initialize the widget again and display the necessary information to the user depending on the error code.

Deletion of callback functions

You can delete the callback functions of the widget using the clearListeners method. This can be useful for single-page apps if the user can leave the page with the widget without reloading the page or sending the form data.

How it works

The widget library subscribes to success or error events every time the user proceeds to the page with the form and you initialize the widget.

In single-page apps this leads to duplication of calls in callback functions during repeat initializations. If the user proceeds to the page with the widget several times, the calls will keep accumulating until the user sends the information via the form or reloads the page.

As a result, when the user sends the bank card information, the library will return the parameters for all accumulated calls for callback functions.

To avoid duplication of the returned parameters, remove callback functions using the clearListeners method every time the user proceeds from the page with the widget to another one within your app.

Example of using the clearListeners method

JavaScript
//Method that, when called, results in the form being hidden or the user leaving the page in a single-page app
onCloseForm(){
  //Вызов метода, который удаляет callback-функции
  payoutsData.clearListeners()
} 

Language configuration

By default, texts in the data collection form are displayed in Russian. To change the interface language to English, set the lang parameter with the en_US value in the widget initialization script.

HTML
<!--HTML element where the form for entering the card number will be placed-->
<div id="payout-form"></div>

<script>
//Widget initialization. All parameters are required.
const payoutsData = new window.PayoutsData({
  type: 'payout',
  account_id: '<Идентификатор_шлюза>', //Идентификатор шлюза (agentId в личном кабинете)
  success_callback: function(data) {
    //Processing the response with card’s token
  },
  error_callback: function(error) {
    //Processing of errors during card token issuance
  },
  lang: 'en_US', //Настройка языка
});

//Отображение формы в контейнере
payoutsData.render('payout-form')
//Метод возвращает Promise, исполнение которого говорит о полной загрузке формы сбора данных (можно не использовать).
  .then(() => {
    //Код, который нужно выполнить после отображения формы.
  });
</script>

Configuring the interface color scheme

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 configured using the colors object set in the customization object when the widget is initialized. The colors object specifies parameters that affect 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.

The number of parameters depends on what you need to change in the form.

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

Color scheme customization options

By default, a widget has a white data collection form with green accent elements such as the Next button. The color scheme can be customized as follows:

Accent elements only: a white form suits your website but the green accent elements don't.
Data collection form only: green accents are fine but a white from isn't suitable (for example, your website has a dark theme).
Full customization (accent elements and shape): default colors don't fit at all and all elements need to be changed.
Selective customization: you need to change some details as the color of payment form borders.

Changing the color of accent elements

Accent elements in the widget help to focus and call to action: Next button, the border of the selected text field.

Two parameters affect the color of accent elements:

control_primary (base color): the background color of the Next button and the color of other accent elements.
control_primary_content: the color of the text inside the button.

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

Parameters that affect the color of accent elements

For control_primary, it’s preferable to use an attention-grabbing color, while for control_primary_content, it’s preferable to use 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. Set the customization object with the colors object and control_primary parameter in the widget initialization script.

HTML
<!--HTML element where the form for entering the card number will be placed-->
<div id="payout-form"></div>

<script>
//Widget initialization. All parameters are required.
const payoutsData = new window.PayoutsData({
  type: 'payout',
  account_id: '<Идентификатор_шлюза>', //Идентификатор шлюза (agentId в личном кабинете)
  //Widget customization
  customization: {
      //Color scheme customization, minimum one parameter, color values in HEX
      colors: {
        control_primary: '#00BF96' // Базовый цвет кнопки Дальше и других акцентных элементов
      }
  },
  success_callback: function(data) {
    //Processing the response with card’s token
  },
  error_callback: function(error) {
    //Processing of errors during card token issuance
  }
});

//Отображение формы в контейнере
payoutsData.render('payout-form')
//Метод возвращает Promise, исполнение которого говорит о полной загрузке формы сбора данных (можно не использовать).
  .then(() => {
    //Код, который нужно выполнить после отображения формы.
  });
</script>

Step 2. Save your changes, open the widget page, and check the bank card data collection form.

Step 3. If necessary, refine the automatically calculated text color inside the Next button. To do this, set the control_primary_content parameter with the color you need in the script, save changes, and refresh the widget page.

JavaScript
    customization: {
        //Color scheme customization, minimum one parameter, color values in HEX
        colors: {
          control_primary: '#00BF96', // Базовый цвет кнопки Дальше и других акцентных элементов
          control_primary_content: '#FFFFFF' // Цвет текста кнопки Дальше
        }
    },

Done! The widget is ready to be used to receive bank card details.

Return to selecting the configuration options

Changing the color of the data collection form

The data collection form consists of a data entry block and the YooMoney's logo.

The background color, where the elements are placed, is the color of your page or the background of the container on your page where the widget is placed. You change this color independently. The Next button is an accent element that is customized separately. All other elements are affected by four parameters:

background (base color): the background color of the main block, color of error messages, and color of tips.
text: text color.
border: color of borders and separators.
control_secondary: color of non-interface elements (for example, color of an inactive input field).

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

Parameters that affect the form color

For background, it's preferable to select a color close to the background color of the container where the widget is placed. For text, it's preferable to select a contrasting color that will be easy to read against the form background, against the background of non-accent elements, and against the container background. 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. Set the customization object with the colors object and background parameter in the widget initialization script.

HTML
<!--HTML element where the form for entering the card number will be placed-->
<div id="payout-form"></div>

<script>
//Widget initialization. All parameters are required.
const payoutsData = new window.PayoutsData({
  type: 'payout',
  account_id: '<Идентификатор_шлюза>', //Идентификатор шлюза (agentId в личном кабинете)
  //Widget customization
  customization: {
      //Color scheme customization, minimum one parameter, color values in HEX
      colors: {
        background: '#F2F3F5' // Цвет фона формы
      }
  },
  success_callback: function(data) {
    //Processing the response with card’s token
  },
  error_callback: function(error) {
    //Processing of errors during card token issuance
  }
});

//Отображение формы в контейнере
payoutsData.render('payout-form')
//Метод возвращает Promise, исполнение которого говорит о полной загрузке формы сбора данных (можно не использовать).
  .then(() => {
    //Код, который нужно выполнить после отображения формы.
  });
</script>

Step 2. Save your changes, open the widget page, and check the bank card data collection form.

Step 3. If necessary, correct the color automatically selected for the text, borders, and non-accent elements. To do this, set additional parameters in the script with the suitable colors, save changes, and refresh the page.

JavaScript
    customization: {
        //Color scheme customization, minimum one parameter, color values in HEX
        colors: {
          background: '#F2F3F5', // Цвет фона формы
          text: '#222222', // Text color
          border: '#D4D4D4', // Color of borders and separators
          control_secondary: '#AFBDCA' // Color of non-accent interface elements
        }
    },

Done! The widget is ready to be used to receive bank card details.

Return to selecting the configuration options

Full color scheme customization

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

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

Step 1. Set the customization object with the colors object, as well as control_primary and background parameters in the widget initialization script.

HTML
<!--HTML element where the form for entering the card number will be placed-->
<div id="payout-form"></div>

<script>
//Widget initialization. All parameters are required.
const payoutsData = new window.PayoutsData({
  type: 'payout',
  account_id: '<Идентификатор_шлюза>', //Идентификатор шлюза (agentId в личном кабинете)
  //Widget customization
  customization: {
      //Color scheme customization, minimum one parameter, color values in HEX
      colors: {
        background: '#F2F3F5', // Цвет фона формы
        control_primary: '#00BF96' // Базовый цвет кнопки Дальше и других акцентных элементов
      }
  },
  success_callback: function(data) {
    //Processing the response with card’s token
  },
  error_callback: function(error) {
    //Processing of errors during card token issuance
  }
});

//Отображение формы в контейнере
payoutsData.render('payout-form')
//Метод возвращает Promise, исполнение которого говорит о полной загрузке формы сбора данных (можно не использовать).
  .then(() => {
    //Код, который нужно выполнить после отображения формы.
  });
</script>

Step 2. Save your changes, open the widget page, and check the bank card data collection form.

JavaScript
    customization: {
        //Color scheme customization, minimum one parameter, color values in HEX
        colors: {
          background: '#F2F3F5', // Цвет фона формы
          control_primary: '#00BF96', // Базовый цвет кнопки Дальше и других акцентных элементов
          control_primary_content: '#FFFFFF', // Цвет текста кнопки Дальше
          control_secondary: '#AFBDCA', // Color of non-accent interface elements
          border: '#D4D4D4', // Color of borders and separators
          text: '#222222' // Text color
        }
    },

Done! The widget is ready to be used to receive bank card details.

Return to selecting the configuration options

Selective color scheme customization

You can use any combination of color scheme parameters. The colors object should contain at least one parameter set (basic or additional). For example, you can change only the color of the form's borders.

For a complete list of all parameters, see a reference for widget. For a detailed explanation of all parameters, see the description of customizing accent elements and data collection form.

Recommended customization order:

Step 1. Set the customization object with the colors object and suitable parameters in the widget initialization script.

HTML
<!--HTML element where the form for entering the card number will be placed-->
<div id="payout-form"></div>

<script>
//Widget initialization. All parameters are required.
const payoutsData = new window.PayoutsData({
  type: 'payout',
  account_id: '<Идентификатор_шлюза>', //Идентификатор шлюза (agentId в личном кабинете)
  //Widget customization
  customization: {
      //Color scheme customization, minimum one parameter, color values in HEX
      colors: {
        //Параметры цветовой схемы, которые вы хотите изменить
      }
  },
  success_callback: function(data) {
    //Processing the response with card’s token
  },
  error_callback: function(error) {
    //Processing of errors during card token issuance
  }
});

//Отображение формы в контейнере
payoutsData.render('payout-form')
//Метод возвращает Promise, исполнение которого говорит о полной загрузке формы сбора данных (можно не использовать).
  .then(() => {
    //Код, который нужно выполнить после отображения формы.
  });
</script>

Step 2. Save changes, open the widget page, and check the bank card data collection form. If necessary, add additional parameters or correct selected colors.

Done! The widget is ready to be used to receive bank card details.

Return to selecting the configuration options

Reference for widget

This reference describes:

Widget versions
Parameters sent when the widget is initialized
Parameters returned after the successful obtaining of bank card details
Parameters returned after an error in processing bank card details
Widget methods

Description of widget versions

The version is specified when the widget is initialized.

https://yookassa.ru/payouts-data/<Версия_виджета>/widget.js

If you'd like to enable new features, make sure your widget version supports them.

Versions are listed in descending order: from new to old ones.

Version	Description
3.1.0	Recommended version. New method added: `clearListeners`is used to delete callback functions on the page with the widget.
3.0.0	The set of parameters, that the library returns in `success_callback` in case of success, has been changed. Changes: `synonim` → name changed to `payout_token`; `panmask` → instead of this parameter, two new ones are returned: `first6` (the first six digits of the card number) and `last4` (the last four digits of the card number); `bankName` → name changed to `issuer_name`; `countryCode` → name changed to `issuer_country`, value returned in the ISO 3166-1 alpha-2 format, example: `RU`; `type` → name changed to `card_type`.
2.0.1	The minimum version required to use the widget. Supports text language configuration and interface color scheme customization.

Reference of parameters for widget initialization

Description of parameters to be sent in the PayoutsData class instance for widget initialization.

Parameter	Type	Description
type	string	Payout type. Fixed value: `payout`, regular payouts (made not via Safe Deal). Required parameter
account_id	string	Gateway ID that will be used to make payouts to bank cards. The ID can be found in the Merchant Profile under the Payout settings section (agentId field). Required parameter
success_callback	(success) => void	Callback function that accepts bank card parameters. Required parameter
error_callback	(error) => void	Callback function that accepts the code of the error in the processing of bank card details. Required parameter
lang	string	Language of interface texts. The format complies with ISO/IEC 15897. Possible values: `ru_RU` for Russian language, `en_US` for English language. The letter case is important. The default language is Russian. Optional parameter
customization	object	Customization of the data collection form. Right now, you can only customize the color scheme. Optional parameter
colors	object	Sent in `customization`. Настройка цветовой схемы. The object sends colors to be changed in the payment form interface. Optional parameter

Reference for color scheme configuration parameters

A description of all colors object parameters that can be used to configure the color scheme.

Parameter	Type	Description	Default
control_primary	string	Background color of accent elements: Next button, the border of selected text field. We recommend using a bright color to draw attention	`#00A884` (green)
control_primary_content	string	Color of the text inside the Next button. We recommend using a color that will contrast with `control_primary`. If the parameter is not specified, the color will be determined on the basis of `control_primary`	`#000000` (black) or `#FFFFFF` (white): it's preferable to select the one that will contrast with `control_primary`.
background	string	The background color of the form, tips, and error messages. We recommend using a color close to the background color of the container where the widget is placed	`#FFFFFF` (white)
text	string	The color of all texts in the form except for texts inside the Next button and pop-up tips. If the parameter is not specified, the color is determined on the basis of `background`	Contrast to `background`
border	string	The color of the form borders. If the parameter is not specified, the color is determined on the basis of `background`	Contrast to `background`
control_secondary	string	Color of non-accent interface elements. If the parameter is not specified, the color is determined on the basis of `background`	Contrast to `background`

Description of the returned parameters in case of success

Description of parameters with bank card details returned by the library in success_callback in case of success.

Parameter	Type	Description
payout_token	string	A bank card synonym is a card ID that used in the YooMoney system and designed to process payouts. Example: `uAFUv0jwtUA_8mMIFeRqzAYw.SC.001.202106` Required parameter
first6	string	The first six digits of the card number that used to display the masked card number to the user. Example: `555555` Required parameter
last4	string	The last four digits of the card number used to display the masked card number to the user. Example: `4477` Required parameter
issuer_name	string	Name of the issuer of the bank card. Example: `YOOMONEY NBCO LLC` Required parameter
issuer_country	string	Code of the country that issued the card. Sent in the ISO 3166-1 alpha-2 format. Example: `RU` (Russia) Required parameter
card_type	string	Type of bank card (name of payment system). Example: `MasterCard` Required parameter

Description of returned parameters in case of error

If there was an error during the processing of bank card details, the widget library will return the error code via error_callback.

Error code	Description
card_country_code_error	You can't make a payout to a bank card issued in this country. Ask the user to enter the details of another bank card.
card_unknown_country_code_error	Incorrect bank card number: unable to determine the code of the country where the card was issued. Ask the user to enter the details again or select another card.
internal_service_error	No specific reason provided. Ask the user to enter the details again or select another card.

Description of widget’s methods

Method	Type	Description
render	(id?: string) => Promise<undefined>	Displaying the payment form. Execution of Promise means the payment form is fully loaded. The use of Promise is optional.
clearListeners	()=>void	Deleting the callback functions of the widget. Required for avoiding the duplication of calls in callback functions during repeat initializations of the widget. Useful in single-page apps if the user can leave the page with the widget without reloading the page or sending form data. Available for the widget version 3.1.0.