Docs
API ЮKassa
Инструкции
Старые версии API
Помощь
Подключить ЮKassa

Подключение виджета для выплат

В этой статье описано, как с помощью виджета для выплат встроить на ваш сайт готовую форму для получения данных банковской карты.
Подготовка к интеграции
Для интеграции вам нужна страница, на которой вы хотите инициализировать виджет и отобразить форму для сбора данных. После получения данных банковской карты вам необходимо сообщить пользователю результаты — отобразить их вместо виджета или перенаправить пользователя на отдельную страницу с результатами.
Для инициализации виджета нужен идентификатор вашего шлюза, с баланса которого вы собираетесь делать выплаты на банковские карты. Идентификатор указан в личном кабинете в разделе Настройки выплат (поле agentId).
Интеграция виджета
Чтобы получить данные банковской карты:
  1. Настройте инициализацию виджета и отображение формы для сбора данных.
  2. Настройте обработку результатов.
  3. При необходимости настройте удаление callback-функций (например, если используете одностраничные приложения).
Инициализация виджета и отображение формы
Шаг 1. Подключите скрипт. Библиотека будет доступна в глобальной области видимости под именем PayoutsData.
HTML
<!--Подключение библиотеки-->
<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-элемент, в котором будет отображаться форма ввода номера карты-->
<div id="payout-form"></div>

<script>
//Инициализация виджета. Все параметры обязательные.
const payoutsData = new window.PayoutsData({
  type: 'payout',
  account_id: '<Идентификатор_шлюза>', //Идентификатор шлюза (agentId в личном кабинете)
  success_callback: function(data) {
    //Обработка ответа с токеном карты
  },
  error_callback: function(error) {
    //Обработка ошибок при получении токена карты
  }
});

//Отображение формы в контейнере
payoutsData.render('payout-form')
//Метод возвращает Promise, исполнение которого говорит о полной загрузке формы сбора данных (можно не использовать).
  .then(() => {
    //Код, который нужно выполнить после отображения формы.
  });
</script>
Если при инициализации виджета что-то пойдет не так, ошибки отобразятся в консоли браузера.
Обработка результата
Когда пользователь отправит номер карты через форму, библиотека вернет результат обработки данных в callback-функцию:
В случае успеха
Если данные обработаны успешно, библиотека передаст в success_callback следующие параметры:
  • Для проведения выплаты: синоним банковской карты (параметр payout_token).
  • Для отображения в интерфейсе информации о банковской карте: первые шесть и последние четыре цифры номера карты, эмитент и страна выпуска карты, тип карты (параметры first6, last4, issuer_name, issuer_country и card_type соответственно).
Описание возвращаемых параметров приведено в справочнике виджета.
Сохраните эти данные. Отобразите пользователю необходимую информацию в зависимости от вашего сценария.
В случае ошибки
Если при обработке данных возникла ошибка, библиотека передаст в error_callback код ошибки.
Инициализируйте виджет заново и отобразите пользователю необходимую информацию в зависимости от кода ошибки.
Удаление callback-функций
Вы можете удалять callback-функции виджета с помощью метода clearListeners. Это пригодится для одностраничных приложений, если пользователь может уходить со страницы с виджетом без перезагрузки страницы или отправки данных формы.
Как это работает
Библиотека виджета подписывается на события успеха или неуспеха каждый раз, когда пользователь переходит на страницу с формой и вы инициализируете виджет.
В одностраничных приложениях это приводит к дублированию вызовов callback-функций при повторных инициализациях. Если пользователь несколько раз переходит на страницу с виджетом, вызовы копятся, пока пользователь не отправит данные через форму или не перезагрузит страницу.
В результате, когда пользователь отправит данные карты, библиотека вернет параметры по всем накопленным вызовам callback-функций.
Чтобы избежать дублирования возвращаемых параметров, удаляйте callback-функции с помощью метода clearListeners каждый раз, когда пользователь переходит со страницы с виджетом на другую внутри вашего приложения.
Пример использования метода clearListeners
JavaScript
//Метод, при вызове которого скрывается форма или пользователь уходит со страницы в одностраничном приложении
onCloseForm(){
  //Вызов метода, который удаляет callback-функции
  payoutsData.clearListeners()
} 
Настройка языка
По умолчанию тексты в форме сбора данных отображаются на русском. Чтобы изменить язык интерфейса на английский, добавьте в скрипт для инициализации виджета параметр lang со значением en_US.
HTML
<!--HTML-элемент, в котором будет отображаться форма ввода номера карты-->
<div id="payout-form"></div>

<script>
//Инициализация виджета. Все параметры обязательные.
const payoutsData = new window.PayoutsData({
  type: 'payout',
  account_id: '<Идентификатор_шлюза>', //Идентификатор шлюза (agentId в личном кабинете)
  success_callback: function(data) {
    //Обработка ответа с токеном карты
  },
  error_callback: function(error) {
    //Обработка ошибок при получении токена карты
  },
  lang: 'en_US', //Настройка языка
});

//Отображение формы в контейнере
payoutsData.render('payout-form')
//Метод возвращает Promise, исполнение которого говорит о полной загрузке формы сбора данных (можно не использовать).
  .then(() => {
    //Код, который нужно выполнить после отображения формы.
  });
</script>
Управление цветовой схемой интерфейса
Виджет можно адаптировать под любой дизайн. Для настройки достаточно задать всего один или два цвета — остальные цвета виджет подберет сам. При необходимости вы можете откорректировать автоматически рассчитанные цвета, передав дополнительные параметры.
Примеры настройки цветовой схемы
Примеры настройки цветовой схемы
Настройка цветовой схемы
Цветовая схема задается при инициализации виджета с помощью объекта colors, переданного в объекте customization. В объекте colors задаются параметры, влияющие на цвета элементов интерфейса.
Можно задать максимум шесть параметров: два базовых и четыре дополнительных. Каждый из базовых параметров отвечает за определенную группу элементов интерфейса. Если передать такой параметр, виджет на его основе рассчитает все нужные цвета. При необходимости вы можете уточнить автоматически подобранные цвета с помощью дополнительных параметров.
Количество передаваемых параметров зависит от того, что вы хотите изменить на форме.

Значения цветов необходимо задавать в шестнадцатеричном представлении (HEX), иначе виджет проигнорирует настройки.

Варианты настройки цветовой схемы
По умолчанию в виджете белая форма для сбора данных, а для важных элементов, например кнопки Дальше, используется акцентный зеленый цвет. Как вы можете настроить цветовую схему:
Изменение цвета акцентных элементов
Акцентные элементы в виджете — это то, что помогает сфокусироваться и призывает к действию: кнопка Дальше, граница выбранного текстового поля.
На цвет акцентных элементов влияют два параметра:
  • control_primary (базовый цвет) — цвет фона кнопки Дальше и цвет других акцентных элементов.
  • control_primary_content — цвет текста в кнопке.

Чтобы изменить цвет акцентных элементов, достаточно передать только control_primary. В этом случае виджет автоматически выберет в качестве цвета текста либо черный, либо белый цвет (наиболее контрастный к control_primary).

Параметры, определяющие цвет акцентных элементов
Параметры, определяющие цвет акцентных элементов
Рекомендуется для control_primary выбирать цвет, привлекающий внимание, для control_primary_content — контрастный цвет, который будет читаться на фоне базового цвета.
Рекомендуется начать настройку с базового цвета, а дополнительный цвет использовать при необходимости:
Шаг 1. Добавьте в скрипт для инициализации виджета объект customization с объектом colors и параметром control_primary.
HTML
<!--HTML-элемент, в котором будет отображаться форма ввода номера карты-->
<div id="payout-form"></div>

<script>
//Инициализация виджета. Все параметры обязательные.
const payoutsData = new window.PayoutsData({
  type: 'payout',
  account_id: '<Идентификатор_шлюза>', //Идентификатор шлюза (agentId в личном кабинете)
  //Настройка виджета
  customization: {
      //Настройка цветовой схемы, минимум один параметр, значения цветов в HEX
      colors: {
        control_primary: '#00BF96' // Базовый цвет кнопки Дальше и других акцентных элементов
      }
  },
  success_callback: function(data) {
    //Обработка ответа с токеном карты
  },
  error_callback: function(error) {
    //Обработка ошибок при получении токена карты
  }
});

//Отображение формы в контейнере
payoutsData.render('payout-form')
//Метод возвращает Promise, исполнение которого говорит о полной загрузке формы сбора данных (можно не использовать).
  .then(() => {
    //Код, который нужно выполнить после отображения формы.
  });
</script>
Шаг 2. Сохраните изменения, откройте страницу с виджетом и проверьте, как смотрится форма для ввода данных карты.
Шаг 3. При необходимости уточните автоматически рассчитанный цвет текста в кнопке Дальше. Для этого добавьте в скрипт параметр control_primary_content с нужным цветом, сохраните изменения и обновите страницу с виджетом.
JavaScript
    customization: {
        //Настройка цветовой схемы, минимум один параметр, значения цветов в HEX
        colors: {
          control_primary: '#00BF96', // Базовый цвет кнопки Дальше и других акцентных элементов
          control_primary_content: '#FFFFFF' // Цвет текста кнопки Дальше
        }
    },
Готово! Виджет можно использовать для получения данных банковской карты.
Изменение цвета формы сбора данных
Форма сбора данных состоит из блока ввода данных и логотипа ЮKassa.
Цвет фона, на котором располагаются элементы, — это цвет вашей страницы или фона контейнера на вашей странице, в котором размещен виджет. Этот цвет вы изменяете самостоятельно. Кнопка Дальше — акцентный элемент, который настраивается отдельно. На все остальные элементы влияют четыре параметра:
  • background (базовый цвет) — цвет фона основного блока, цвет сообщений об ошибках и цвет подсказок.
  • text — цвет текста.
  • border — цвет границ и разделителей.
  • control_secondary — цвет неакцентных элементов интерфейса (например, цвет неактивного поля ввода).

Чтобы изменить цвет формы для сбора данных, достаточно передать только background. В этом случае цвет границ, текста и неакцентных элементов виджет рассчитает автоматически.

Параметры, определяющие цвет формы
Параметры, определяющие цвет формы
Рекомендуется для background выбирать цвет, близкий к цвету фона контейнера, в котором размещен виджет, для text — контрастный цвет, который будет читаться на фоне формы, на фоне неакцентных элементов и на фоне контейнера. Остальные цвета рекомендуется подбирать так, чтобы они хорошо смотрелись на фоне background.
Рекомендуется начать настройку с базового цвета, а дополнительные цвета использовать при необходимости:
Шаг 1. Добавьте в скрипт для инициализации виджета объект customization с объектом colors и параметром background.
HTML
<!--HTML-элемент, в котором будет отображаться форма ввода номера карты-->
<div id="payout-form"></div>

<script>
//Инициализация виджета. Все параметры обязательные.
const payoutsData = new window.PayoutsData({
  type: 'payout',
  account_id: '<Идентификатор_шлюза>', //Идентификатор шлюза (agentId в личном кабинете)
  //Настройка виджета
  customization: {
      //Настройка цветовой схемы, минимум один параметр, значения цветов в HEX
      colors: {
        background: '#F2F3F5' // Цвет фона формы
      }
  },
  success_callback: function(data) {
    //Обработка ответа с токеном карты
  },
  error_callback: function(error) {
    //Обработка ошибок при получении токена карты
  }
});

//Отображение формы в контейнере
payoutsData.render('payout-form')
//Метод возвращает Promise, исполнение которого говорит о полной загрузке формы сбора данных (можно не использовать).
  .then(() => {
    //Код, который нужно выполнить после отображения формы.
  });
</script>
Шаг 2. Сохраните изменения, откройте страницу с виджетом и проверьте, как смотрится форма для ввода данных карты.
Шаг 3. При необходимости уточните автоматически рассчитанные цвета текстов, границ или неакцентных элементов. Для этого добавьте в скрипт дополнительные параметры с нужными цветами, сохраните изменения и обновите страницу.
JavaScript
    customization: {
        //Настройка цветовой схемы, минимум один параметр, значения цветов в HEX
        colors: {
          background: '#F2F3F5', // Цвет фона формы
          text: '#222222', // Цвет текста
          border: '#D4D4D4', // Цвет границ и разделителей
          control_secondary: '#AFBDCA' // Цвет неакцентных элементов интерфейса
        }
    },
Готово! Виджет можно использовать для получения данных банковской карты.
Полная настройка цветовой схемы
Если вы хотите поменять все цвета виджета, используйте одновременно параметры для изменения акцентных элементов и платежной формы.
Рекомендуется начать настройку с базовых цветов, а дополнительные цвета использовать при необходимости:
Шаг 1. Добавьте в скрипт для инициализации виджета объект customization с объектом colors и параметрами control_primary и background.
HTML
<!--HTML-элемент, в котором будет отображаться форма ввода номера карты-->
<div id="payout-form"></div>

<script>
//Инициализация виджета. Все параметры обязательные.
const payoutsData = new window.PayoutsData({
  type: 'payout',
  account_id: '<Идентификатор_шлюза>', //Идентификатор шлюза (agentId в личном кабинете)
  //Настройка виджета
  customization: {
      //Настройка цветовой схемы, минимум один параметр, значения цветов в HEX
      colors: {
        background: '#F2F3F5', // Цвет фона формы
        control_primary: '#00BF96' // Базовый цвет кнопки Дальше и других акцентных элементов
      }
  },
  success_callback: function(data) {
    //Обработка ответа с токеном карты
  },
  error_callback: function(error) {
    //Обработка ошибок при получении токена карты
  }
});

//Отображение формы в контейнере
payoutsData.render('payout-form')
//Метод возвращает Promise, исполнение которого говорит о полной загрузке формы сбора данных (можно не использовать).
  .then(() => {
    //Код, который нужно выполнить после отображения формы.
  });
</script>
Шаг 2. Сохраните изменения, откройте страницу с виджетом и проверьте, как смотрится форма для ввода данных карты.
Шаг 3. При необходимости уточните автоматически рассчитанные цвета текстов, границ или неакцентных элементов. Для этого добавьте в скрипт дополнительные параметры с нужными цветами, сохраните изменения и обновите страницу.
JavaScript
    customization: {
        //Настройка цветовой схемы, минимум один параметр, значения цветов в HEX
        colors: {
          background: '#F2F3F5', // Цвет фона формы
          control_primary: '#00BF96', // Базовый цвет кнопки Дальше и других акцентных элементов
          control_primary_content: '#FFFFFF', // Цвет текста кнопки Дальше
          control_secondary: '#AFBDCA', // Цвет неакцентных элементов интерфейса
          border: '#D4D4D4', // Цвет границ и разделителей
          text: '#222222' // Цвет текста
        }
    },
Готово! Виджет можно использовать для получения данных банковской карты.
Произвольная настройка цветовой схемы
Вы можете использовать любую комбинацию параметров цветовой схемы. В объекте colors нужно предать как минимум один параметр (базовый или дополнительный). Например, вы можете изменить только цвет границ формы.
Полный перечень всех параметров приведен в справочнике виджета. Подробное объяснение, за что отвечает каждый параметр, приведено в описании настройки акцентных элементов и формы сбора данных.
Рекомендуемый порядок настройки:
Шаг 1. Добавьте в скрипт для инициализации виджета объект customization с объектом colors и нужными вам параметрами.
HTML
<!--HTML-элемент, в котором будет отображаться форма ввода номера карты-->
<div id="payout-form"></div>

<script>
//Инициализация виджета. Все параметры обязательные.
const payoutsData = new window.PayoutsData({
  type: 'payout',
  account_id: '<Идентификатор_шлюза>', //Идентификатор шлюза (agentId в личном кабинете)
  //Настройка виджета
  customization: {
      //Настройка цветовой схемы, минимум один параметр, значения цветов в HEX
      colors: {
        //Параметры цветовой схемы, которые вы хотите изменить
      }
  },
  success_callback: function(data) {
    //Обработка ответа с токеном карты
  },
  error_callback: function(error) {
    //Обработка ошибок при получении токена карты
  }
});

//Отображение формы в контейнере
payoutsData.render('payout-form')
//Метод возвращает Promise, исполнение которого говорит о полной загрузке формы сбора данных (можно не использовать).
  .then(() => {
    //Код, который нужно выполнить после отображения формы.
  });
</script>
Шаг 2. Сохраните изменения, откройте страницу с виджетом и проверьте, как смотрится форма для ввода данных карты. При необходимости добавьте дополнительные параметры или уточните выбранные цвета.
Готово! Виджет можно использовать для получения данных банковской карты.
Справочник виджета
В этом справочнике описаны:
Описание версий виджета
Версия указывается при инициализации виджета.
https://yookassa.ru/payouts-data/<Версия_виджета>/widget.js
Если вы хотите подключить новую функциональность, убедитесь, что ваша версия виджета поддерживает ее.
Версии перечислены в порядке убывания — от новых к старым.
ВерсияОписание
Рекомендуемая версия.
Добавлен новый метод — clearListeners, который удаляет callback-функции на странице с виджетом.
Изменен набор параметров, которые библиотека возвращает в 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
Тип выплаты. Возможные значения:
Обязательный параметр
account_id
string
Для обычных выплат: идентификатор шлюза, с баланса которого вы собираетесь делать выплаты на банковские карты. Идентификатор указан в личном кабинете в разделе Настройки выплат (поле agentId).
Для выплат в рамках Безопасной сделки: идентификатор магазина, который вы используете для приема платежей. Идентификатор указан в личном кабинете в разделе Настройки магазина (поле shopid).
Обязательный параметр
success_callback
(success) => void
Callback-функция, которая принимает параметры банковской карты.
Обязательный параметр
error_callback
(error) => void
Callback-функция, которая принимает код ошибки обработки данных банковской карты.
Обязательный параметр
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
Описание возвращаемых параметров в случае успеха
Описание параметров с данными банковской карты, которые библиотека возвращает в 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
Обязательный параметр
Описание возвращаемых параметров при ошибке
Если при обработке данных банковской карты возникла ошибка, библиотека виджета передаст в error_callback код ошибки.
Код ошибкиОписание
card_country_code_errorНельзя сделать выплату на банковскую карту, выпущенную в этой стране. Попросите пользователя ввести данные другой карты.
card_unknown_country_code_errorНеправильный номер банковской карты: невозможно определить код страны, в которой выпущена карта. Попросите пользователя ввести данные еще раз или выбрать другую карту.
internal_service_errorПричина не детализирована. Попросите пользователя ввести данные еще раз или выбрать другую карту.
Описание методов виджета
МетодТипОписание
render(id?: string) => Promise<undefined>Отображает платежную форму. Исполнение Promise говорит о полной загрузке платежной формы. Promise можно не использовать.
clearListeners
()=>void
Удаляет callback-функции виджета. Нужен, чтобы избежать дублирования вызовов callback-функций при повторных инициализациях виджета. Пригодится в одностраничных приложениях, если пользователь может уходить со страницы с виджетом без перезагрузки страницы или отправки данных формы.
Доступен для версии виджета 3.1.0.
Что почитать еще
© 2025, ООО НКО «ЮМани»