YooMoney API
Guides
Old versions of the API
Help
Sign up for YooMoney
Подключение виджета для выплат
В этой статье описано, как с помощью виджета для выплат встроить на ваш сайт готовую форму для получения данных банковской карты.
 
Подготовка к интеграции
Для интеграции вам нужна страница, на которой вы хотите инициализировать виджет и отобразить форму для сбора данных. После получения данных банковской карты вам необходимо сообщить пользователю результаты — отобразить их вместо виджета или перенаправить пользователя на отдельную страницу с результатами.
Для инициализации виджета нужен идентификатор вашего шлюза, с баланса которого вы собираетесь делать выплаты на банковские карты. Идентификатор указан в личном кабинете в разделе Настройки выплат (поле agentId).
Интеграция виджета
To get the bank card information:
  1. Set up widget initialization and the displaying of the form for collecting information.
  2. Set up the processing of results.
  3. If necessary, set up the deletion of callback functions (for example, if you use single-page apps).
Инициализация виджета и отображение формы
Шаг 1. Подключите скрипт. Библиотека будет доступна в глобальной области видимости под именем PayoutsData.
HTML
<!--Library implementation-->
<script src="https://yookassa.ru/payouts-data/3.1.0/widget.js"></script>

Шаг 2. На страницу получения данных банковской карты добавьте HTML-элемент, в котором хотите разместить форму. Задайте для этого элемента атрибут id.
Шаг 3. Для инициализации виджета создайте новый экземпляр класса PayoutsData, передайте в него следующие параметры:
  • type со значением payout;
  • account_id с идентификатором шлюза;
  • success_callback, который будет принимать параметры карты;
  • error_callback, который будет принимать код ошибки.
При необходимости передайте параметры для настройки языка текстов и для управления цветовой схемой интерфейса.
Шаг 4. Чтобы отобразить форму ввода номера карты, вызовите метод render. Передайте в него значение атрибута id, в котором нужно разместить форму, и при необходимости код, который нужно выполнить после отображения формы.
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.
Обработка результата
After the user sends the card number via the form, the library will return the results of the data processing as a callback function:
In case of success
If the data is processed successfully, the library will return the following parameters via success_callback:
  • Для проведения выплаты: синоним банковской карты (параметр payout_token).
  • Для отображения в интерфейсе информации о банковской карте: первые шесть и последние четыре цифры номера карты, эмитент и страна выпуска карты, тип карты (параметры first6, last4, issuer_name, issuer_country и card_type соответственно).
Описание возвращаемых параметров приведено в справочнике виджета.
Save this information. Display the necessary information to the user depending on your scenario.
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()
} 
Настройка языка
По умолчанию тексты в форме сбора данных отображаются на русском. Чтобы изменить язык интерфейса на английский, добавьте в скрипт для инициализации виджета параметр lang со значением en_US.
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>
Управление цветовой схемой интерфейса
Виджет можно адаптировать под любой дизайн. Для настройки достаточно задать всего один или два цвета — остальные цвета виджет подберет сам. При необходимости вы можете откорректировать автоматически рассчитанные цвета, передав дополнительные параметры.
Примеры настройки цветовой схемы
Настройка цветовой схемы
Цветовая схема задается при инициализации виджета с помощью объекта colors, переданного в объекте customization. В объекте colors задаются параметры, влияющие на цвета элементов интерфейса.
Можно задать максимум шесть параметров: два базовых и четыре дополнительных. Каждый из базовых параметров отвечает за определенную группу элементов интерфейса. Если передать такой параметр, виджет на его основе рассчитает все нужные цвета. При необходимости вы можете уточнить автоматически подобранные цвета с помощью дополнительных параметров.
Количество передаваемых параметров зависит от того, что вы хотите изменить на форме.
Варианты настройки цветовой схемы
По умолчанию в виджете белая форма для сбора данных, а для важных элементов, например кнопки Дальше, используется акцентный зеленый цвет. Как вы можете настроить цветовую схему:
Изменение цвета акцентных элементов
Акцентные элементы в виджете — это то, что помогает сфокусироваться и призывает к действию: кнопка Дальше, граница выбранного текстового поля.
На цвет акцентных элементов влияют два параметра:
  • control_primary (базовый цвет) — цвет фона кнопки Дальше и цвет других акцентных элементов.
  • control_primary_content — цвет текста в кнопке.
Параметры, определяющие цвет акцентных элементов
Рекомендуется для control_primary выбирать цвет, привлекающий внимание, для control_primary_content — контрастный цвет, который будет читаться на фоне базового цвета.
Рекомендуется начать настройку с базового цвета, а дополнительный цвет использовать при необходимости:
Шаг 1. Добавьте в скрипт для инициализации виджета объект customization с объектом colors и параметром control_primary.
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>
Шаг 2. Сохраните изменения, откройте страницу с виджетом и проверьте, как смотрится форма для ввода данных карты.
Шаг 3. При необходимости уточните автоматически рассчитанный цвет текста в кнопке Дальше. Для этого добавьте в скрипт параметр control_primary_content с нужным цветом, сохраните изменения и обновите страницу с виджетом.
JavaScript
    customization: {
        //Color scheme customization, minimum one parameter, color values in HEX
        colors: {
          control_primary: '#00BF96', // Базовый цвет кнопки Дальше и других акцентных элементов
          control_primary_content: '#FFFFFF' // Цвет текста кнопки Дальше
        }
    },
Готово! Виджет можно использовать для получения данных банковской карты.
Изменение цвета формы сбора данных
Форма сбора данных состоит из блока ввода данных и логотипа ЮKassa.
Цвет фона, на котором располагаются элементы, — это цвет вашей страницы или фона контейнера на вашей странице, в котором размещен виджет. Этот цвет вы изменяете самостоятельно. Кнопка Дальше — акцентный элемент, который настраивается отдельно. На все остальные элементы влияют четыре параметра:
  • background (базовый цвет) — цвет фона основного блока, цвет сообщений об ошибках и цвет подсказок.
  • text — цвет текста.
  • border — цвет границ и разделителей.
  • control_secondary — цвет неакцентных элементов интерфейса (например, цвет неактивного поля ввода).
Параметры, определяющие цвет формы
Рекомендуется для background выбирать цвет, близкий к цвету фона контейнера, в котором размещен виджет, для text — контрастный цвет, который будет читаться на фоне формы, на фоне неакцентных элементов и на фоне контейнера. Остальные цвета рекомендуется подбирать так, чтобы они хорошо смотрелись на фоне background.
Рекомендуется начать настройку с базового цвета, а дополнительные цвета использовать при необходимости:
Шаг 1. Добавьте в скрипт для инициализации виджета объект customization с объектом colors и параметром background.
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>
Шаг 2. Сохраните изменения, откройте страницу с виджетом и проверьте, как смотрится форма для ввода данных карты.
Шаг 3. При необходимости уточните автоматически рассчитанные цвета текстов, границ или неакцентных элементов. Для этого добавьте в скрипт дополнительные параметры с нужными цветами, сохраните изменения и обновите страницу.
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
        }
    },
Готово! Виджет можно использовать для получения данных банковской карты.
Полная настройка цветовой схемы
Если вы хотите поменять все цвета виджета, используйте одновременно параметры для изменения акцентных элементов и платежной формы.
Рекомендуется начать настройку с базовых цветов, а дополнительные цвета использовать при необходимости:
Шаг 1. Добавьте в скрипт для инициализации виджета объект customization с объектом colors и параметрами control_primary и background.
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>
Шаг 2. Сохраните изменения, откройте страницу с виджетом и проверьте, как смотрится форма для ввода данных карты.
Шаг 3. При необходимости уточните автоматически рассчитанные цвета текстов, границ или неакцентных элементов. Для этого добавьте в скрипт дополнительные параметры с нужными цветами, сохраните изменения и обновите страницу.
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
        }
    },
Готово! Виджет можно использовать для получения данных банковской карты.
Произвольная настройка цветовой схемы
Вы можете использовать любую комбинацию параметров цветовой схемы. В объекте colors нужно предать как минимум один параметр (базовый или дополнительный). Например, вы можете изменить только цвет границ формы.
Полный перечень всех параметров приведен в справочнике виджета. Подробное объяснение, за что отвечает каждый параметр, приведено в описании настройки акцентных элементов и формы сбора данных.
Рекомендуемый порядок настройки:
Шаг 1. Добавьте в скрипт для инициализации виджета объект customization с объектом colors и нужными вам параметрами.
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>
Шаг 2. Сохраните изменения, откройте страницу с виджетом и проверьте, как смотрится форма для ввода данных карты. При необходимости добавьте дополнительные параметры или уточните выбранные цвета.
Готово! Виджет можно использовать для получения данных банковской карты.
Справочник виджета
В этом справочнике описаны:
Описание версий виджета
Версия указывается при инициализации виджета.
https://yookassa.ru/payouts-data/<Версия_виджета>/widget.js
Если вы хотите подключить новую функциональность, убедитесь, что ваша версия виджета поддерживает ее.
Версии перечислены в порядке убывания — от новых к старым.
ВерсияОписание
Recommended version.
New method added: clearListeners, used for deleting callback functions on the page with the widget.
Изменен набор параметров, которые библиотека возвращает в success_callback при успехе. Что изменилось:
  • synonim → название изменено на payout_token;
  • panmask → вместо этого параметра возвращается два новых: first6 (первые шесть цифр номера карты) и last4 (последние четыре цифры номера карты);
  • bankName → название изменено на issuer_name;
  • countryCode → название изменено на issuer_country, значение возвращается в формате ISO 3166-1 alpha-2, пример: RU;
  • type → название изменено на card_type.
2.0.1Минимально необходимая версия для использования виджета. Поддерживает настройку языка текстов и цветовой схемы интерфейса формы.
Описание параметров для инициализации виджета
Описание параметров, которые необходимо передать в экземпляр класса PayoutsData для инициализации виджета.
ПараметрТипОписание
type
string
Тип выплаты. Фиксированное значение: payout — обычные выплаты (не в рамках Безопасной сделки).
Обязательный параметр
account_id
string
Идентификатор шлюза, с баланса которого вы собираетесь делать выплаты на банковские карты. Идентификатор указан в личном кабинете в разделе Настройки выплат (поле agentId).
Обязательный параметр
success_callback
(success) => void
Callback-функция, которая принимает параметры банковской карты.
Обязательный параметр
error_callback
(error) => void
Callback function that accepts the code of the error in the processing of bank card details.
Обязательный параметр
lang
string
Язык, на котором отображаются тексты интерфейса. Формат соответствует ISO/IEC 15897. Возможные значения: ru_RU — русский язык, en_US — английский язык. Регистр важен. По умолчанию используется русский язык.
Необязательный параметр
customization
object
Настройка формы для сбора данных. Сейчас можно настроить только цветовую схему.
Необязательный параметр
colors
object
Передается в customization.
Настройка цветовой схемы. В объекте передаются цвета, которые нужно изменить в интерфейсе платежной формы.
Необязательный параметр
Описание параметров для настройки цветовой схемы
Описание всех параметров объекта colors, которые можно использовать для настройки цветовой схемы.
ПараметрТипОписаниеПо умолчанию
control_primarystringЦвет фона акцентных элементов: кнопка Дальше, граница выбранного текстового поля. Рекомендуется использовать яркий цвет, привлекающий внимание#00A884 (зеленый)
control_primary_contentstringЦвет текста в кнопке Дальше. Рекомендуется использовать цвет, контрастный к control_primary.
Если параметр не передан, цвет рассчитывается на основе control_primary
#000000 (черный) или #FFFFFF (белый) — выбирается контрастный к control_primary
backgroundstringЦвет фона формы, подсказок и сообщений об ошибках. Рекомендуется использовать цвет, близкий к цвету фона контейнера, в котором размещен виджет#FFFFFF (белый)
textstringЦвет всех текстов на форме, кроме текстов в кнопке Дальше и во всплывающих подсказках.
Если параметр не передан, цвет рассчитывается на основе background
Контрастный к background
borderstringЦвет границы формы.
Если параметр не передан, цвет рассчитывается на основе background
Контрастный к background
control_secondarystringЦвет неакцентных элементов интерфейса.
Если параметр не передан, цвет рассчитывается на основе background
Контрастный к background
Description of the returned parameters in case of success
Описание параметров с данными банковской карты, которые библиотека возвращает в success_callback при успехе.
ПараметрТипОписание
payout_token
string
Синоним банковской карты — идентификатор карты в системе ЮKassa, который нужно использовать для проведения выплат.
Пример: uAFUv0jwtUA_8mMIFeRqzAYw.SC.001.202106
Обязательный параметр
first6
string
Первые шесть цифр номера карты, для отображения пользователю номера карты в маскированном виде.
Пример: 555555
Обязательный параметр
last4
string
Последние четыре цифры номера карты, для отображения пользователю номера карты в маскированном виде.
Пример: 4477
Обязательный параметр
issuer_name
string
Наименование эмитента, выпустившего банковскую карту.
Пример: YOOMONEY NBCO LLC
Обязательный параметр
issuer_country
string
Код страны, в которой выпущена карта. Передается в формате ISO 3166-1 alpha-2.
Пример: RU (Россия)
Обязательный параметр
card_type
string
Тип банковской карты (наименование платежной системы).
Пример: MasterCard
Обязательный параметр
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 codeDescription
card_country_code_errorYou 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_errorIncorrect 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_errorNo specific reason provided. Ask the user to enter the details again or select another card.
Описание методов виджета
МетодТипОписание
render(id?: string) => Promise<undefined>Displaying the payment form. Исполнение Promise говорит о полной загрузке платежной формы. Promise можно не использовать.
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.
See also