Docs
Инструкции
Помощь
Подключить ЮKassa
Подключение виджета для выплат
В этой статье описано, как с помощью виджета для выплат встроить на ваш сайт готовую форму для получения данных банковской карты.
Подготовка к интеграции
Для интеграции вам нужна страница, на которой вы хотите инициализировать виджет и отобразить форму для сбора данных. После получения данных банковской карты вам необходимо сообщить пользователю результаты — отобразить их вместо виджета или перенаправить пользователя на отдельную страницу с результатами.
Для инициализации виджета нужен идентификатор вашего шлюза, с баланса которого вы собираетесь делать выплаты на банковские карты. Идентификатор указан в личном кабинете в разделе Настройки выплат (поле agentId).
Интеграция виджета
Для получения данных банковской карты вам нужно:
  1. Настроить инициализацию виджета и отображение формы для сбора данных.
  2. Настроить обработку результатов.
Инициализация виджета и отображение формы
Шаг 1. Подключите скрипт. Библиотека будет доступна в глобальной области видимости под именем
PayoutsData
.
HTML

<script src="https://yookassa.ru/payouts-data/3.0.0/widget.js"></script>
Шаг 2. На страницу получения данных банковской карты добавьте HTML-элемент, в котором хотите разместить форму. Задайте для этого элемента атрибут
id
.
Шаг 3. Для инициализации виджета создайте новый экземпляр класса
PayoutsData
, передайте в него следующие параметры:
  • type
    со значением
    payout
    ;
  • account_id
    с идентификатором шлюза;
  • success_callback
    , который будет принимать параметры карты;
  • error_callback
    , который будет принимать код ошибки.
При необходимости передайте параметры для настройки языка текстов и для управления цветовой схемой интерфейса.
Шаг 4. Чтобы отобразить форму ввода номера карты, вызовите метод
render
. Передайте в него значение атрибута
id
, в котором нужно разместить форму, и при необходимости код, который нужно выполнить после отображения формы.
HTML

<div id="payout-form"></div>

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

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

<div id="payout-form"></div>

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

<div id="payout-form"></div>

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

<div id="payout-form"></div>

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

<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(data) {
    //Обработка ответа с токеном карты
  },
  error_callback(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

<div id="payout-form"></div>

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

//Отображение формы в контейнере
payoutsData.render('payout-form')
//Метод возвращает Promise, исполнение которого говорит о полной загрузке формы сбора данных (можно не использовать).
  .then(() => {
    //Код, который нужно выполнить после отображения формы.
  });
</script>
Шаг 2. Сохраните изменения, откройте страницу с виджетом и проверьте, как смотрится форма для ввода данных карты. При необходимости добавьте дополнительные параметры или уточните выбранные цвета.
Готово! Виджет можно использовать для получения данных банковской карты.
Справочник виджета
В этом справочнике описаны:
Описание версий виджета
Версия указывается при инициализации виджета.
https://yookassa.ru/payouts-data/<Версия_виджета>/widget.js
Если вы хотите подключить новую функциональность, убедитесь, что ваша версия виджета поддерживает ее.
Версии перечислены в порядке убывания — от новых к старым.
ВерсияОписание
3.0.0
Рекомендуемая версия.
Изменен набор параметров, которые библиотека возвращает в 
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
для инициализации виджета.
ПараметрТипОписание
typestring
Тип выплаты. Фиксированное значение:
payout
 — обычные выплаты (не в рамках Безопасной сделки).
Обязательный параметр
account_idstring
Идентификатор шлюза, с баланса которого вы собираетесь делать выплаты на банковские карты. Идентификатор указан в личном кабинете в разделе Настройки выплат (поле agentId).
Обязательный параметр
success_callback(success) => void
Callback-функция, которая принимает параметры банковской карты.
Обязательный параметр
error_callback(error) => void
Callback-функция, которая принимает код ошибки инициализации.
Обязательный параметр
langstring
Язык, на котором отображаются тексты интерфейса. Формат соответствует ISO/IEC 15897. Возможные значения:
ru_RU
 — русский язык,
en_US
 — английский язык. Регистр важен. По умолчанию используется русский язык.
Необязательный параметр
customizationobject
Настройка формы для сбора данных. Сейчас можно настроить только цветовую схему.
Необязательный параметр
colorsobject
Передается в 
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_tokenstring
Синоним банковской карты — идентификатор карты в системе ЮKassa, который нужно использовать для проведения выплат.
Пример:
uAFUv0jwtUA_8mMIFeRqzAYw.SC.001.202106
Обязательный параметр
first6string
Первые шесть цифр номера карты, для отображения пользователю номера карты в маскированном виде.
Пример:
555555
Обязательный параметр
last4string
Последние четыре цифры номера карты, для отображения пользователю номера карты в маскированном виде.
Пример:
4477
Обязательный параметр
issuer_namestring
Наименование эмитента, выпустившего банковскую карту.
Пример:
YOOMONEY NBCO LLC
Обязательный параметр
issuer_countrystring
Код страны, в которой выпущена карта. Передается в формате ISO 3166-1 alpha-2.
Пример:
RU
(Россия)
Обязательный параметр
card_typestring
Тип банковской карты (наименование платежной системы).
Пример:
MasterCard
Обязательный параметр
Описание методов виджета
МетодТипОписание
render(id?: string) => Promise<undefined>
Отображение платежной формы. Исполнение Promise говорит о полной загрузке платежной формы. Promise можно не использовать.
Что почитать еще
Проведение выплат с использованием синонима карты