Подключение виджета для выплат
В этой статье описано, как с помощью виджета для выплат встроить на ваш сайт готовую форму для получения данных банковской карты.
Для интеграции вам нужна страница, на которой вы хотите инициализировать виджет и отобразить форму для сбора данных. После получения данных банковской карты вам необходимо сообщить пользователю результаты — отобразить их вместо виджета или перенаправить пользователя на отдельную страницу с результатами.
Для инициализации виджета нужен идентификатор вашего шлюза, с баланса которого вы собираетесь делать выплаты на банковские карты. Идентификатор указан в личном кабинете в разделе Настройки выплат (поле agentId).
To get the bank card information:
- Set up widget initialization and the displaying of the form for collecting information.
- Set up the processing of results.
- If necessary, set up the deletion of callback functions (for example, if you use single-page apps).
Шаг 1. Подключите скрипт. Библиотека будет доступна в глобальной области видимости под именем
PayoutsData
.<!--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 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:
success_callback
in case of success;error_callback
in case of error.
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.
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.
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.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
//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 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 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
с нужным цветом, сохраните изменения и обновите страницу с виджетом.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 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. При необходимости уточните автоматически рассчитанные цвета текстов, границ или неакцентных элементов. Для этого добавьте в скрипт дополнительные параметры с нужными цветами, сохраните изменения и обновите страницу.
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 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. При необходимости уточните автоматически рассчитанные цвета текстов, границ или неакцентных элементов. Для этого добавьте в скрипт дополнительные параметры с нужными цветами, сохраните изменения и обновите страницу.
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 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. Сохраните изменения, откройте страницу с виджетом и проверьте, как смотрится форма для ввода данных карты. При необходимости добавьте дополнительные параметры или уточните выбранные цвета.
Готово! Виджет можно использовать для получения данных банковской карты.
В этом справочнике описаны:
- Версии виджета
- Параметры, которые передаются при инициализации виджета
- Parameters returned after the successful obtaining of bank card details
- Parameters returned after an error in processing bank card details
- Методы виджета
Версия указывается при инициализации виджета.
https://yookassa.ru/payouts-data/<Версия_виджета>/widget.js
Если вы хотите подключить новую функциональность, убедитесь, что ваша версия виджета поддерживает ее.
Версии перечислены в порядке убывания — от новых к старым.
Версия | Описание |
---|---|
Recommended version. | |
Изменен набор параметров, которые библиотека возвращает в success_callback при успехе. Что изменилось:
| |
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_primary | string | Цвет фона акцентных элементов: кнопка Дальше, граница выбранного текстового поля. Рекомендуется использовать яркий цвет, привлекающий внимание | #00A884 (зеленый) |
control_primary_content | string | Цвет текста в кнопке Дальше. Рекомендуется использовать цвет, контрастный к control_primary . Если параметр не передан, цвет рассчитывается на основе control_primary | #000000 (черный) или #FFFFFF (белый) — выбирается контрастный к control_primary |
background | string | Цвет фона формы, подсказок и сообщений об ошибках. Рекомендуется использовать цвет, близкий к цвету фона контейнера, в котором размещен виджет | #FFFFFF (белый) |
text | string | Цвет всех текстов на форме, кроме текстов в кнопке Дальше и во всплывающих подсказках. Если параметр не передан, цвет рассчитывается на основе background | Контрастный к background |
border | string | Цвет границы формы. Если параметр не передан, цвет рассчитывается на основе background | Контрастный к background |
control_secondary | string | Цвет неакцентных элементов интерфейса. Если параметр не передан, цвет рассчитывается на основе 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 Обязательный параметр |
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. |
Метод | Тип | Описание |
---|---|---|
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