Виджет ЮKassa позволяет встроить на сайт готовую платежную форму. Пользователю будет доступно несколько способов оплаты: кошелек ЮMoney и привязанные к нему банковские карты, произвольная банковская карта, Apple Pay, Google Pay и Сбербанк Онлайн. С помощью виджета пользователь сможет сохранить в вашем магазине банковскую карту или кошелек ЮMoney для автоплатежей.
Платежная форма виджета ЮKassa
Платежная форма автоматически подстраивается под размеры устройства пользователя, проверяет вводимые данные и подсказывает пользователю, если что-то введено некорректно. Можно настроить язык интерфейса и цветовую схему платежной формы.
Чтобы принять платеж с помощью виджета, достаточно создать платеж по API ЮKassa, инициализировать виджет и отобразить форму на странице оплаты.
Для интеграции:
- Ознакомьтесь со сценарием проведения платежа в виджете.
- Настройте способы оплаты.
- Подготовьте страницу оплаты.
- Реализуйте проведение платежей.
- При необходимости реализуйте проведение автоплатежей.
- При необходимости настройте цветовую схему виджета.
- Настройте обработку ошибок инициализации виджета.
- Пользователь переходит к оплате.
- Вы отправляете ЮKassa запрос на создание платежа.
- ЮKassa возвращает вам созданный объект платежа с токеном для инициализации виджета.
- Вы инициализируете виджет и отображаете форму на странице оплаты.
- Пользователь выбирает способ оплаты, вводит данные.
- При необходимости виджет перенаправляет пользователя на страницу подтверждения платежа или отображает всплывающее окно (например, для аутентификации по 3-D Secure).
- Пользователь подтверждает платеж.
- Виджет перенаправляет пользователя на страницу завершения оплаты на вашей стороне.
- Вы отображаете нужную информацию, в зависимости от статуса платежа.
Готово!
Виджет поддерживает следующие способы оплаты:
- кошелек ЮMoney и привязанные к нему карты,
- произвольная банковская карта,
- Apple Pay,
- Google Pay,
- Сбербанк Онлайн.
По умолчанию доступна оплата кошельком ЮMoney и с привязанных карт. Уточните у менеджера ЮKassa, какие еще способы оплаты вам разрешены.
Чтобы в виджете работала оплата с помощью Apple Pay и Google Pay, ваш сайт должен использовать HTTPS и действующий TLS/SSL-сертификат (минимальная версия — TLS v1.2). Для подключения Apple Pay выполните дополнительные настройки.
Подключая Apple Pay в виджете, вы соглашаетесь с условиями использования платежного сервиса Apple Pay.
Шаг 1. Сообщите вашему менеджеру ЮKassa адрес сайта, на котором будет размещаться виджет.
Шаг 2. Скачайте файл apple-developer-merchantid-domain-association и разместите его на своем сайте по адресу:
https://<домен вашего сайта>/.well-known/
Названия файла и папки на вашем сайте должны быть строго такими — с точкой и дефисами. Точка в названии означает, что это скрытая папка.
Шаг 3. Чтобы оплата с помощью Apple Pay всегда была доступна в виджете, обновляйте TLS/SSL-сертификат не позднее, чем за 8 дней до окончания его срока действия.
Для приема платежей подготовьте страницу оплаты: подключите библиотеку и разместите виджет.
Шаг 1. Подключите скрипт. Библиотека будет доступна в глобальной области видимости под именем
YooMoneyCheckoutWidget
.Шаг 2. На страницу оплаты добавьте HTML-элемент, в котором хотите разместить форму. Задайте для данного элемента атрибут
id
.Шаг 3. Для инициализации виджета создайте новый экземпляр класса
YooMoneyCheckoutWidget
и передайте в него confirmation_token
, который нужно получить в ЮKassa перед проведением платежа, return_url
, на который пользователь вернется после оплаты, и callback-функцию, которая будет принимать код ошибки. При необходимости настройте цветовую схему.confirmation_token
нужно получать в ЮKassa для каждого платежа.
Шаг 4. Чтобы отобразить платежную форму, вызовите метод
render
. Передайте в него значение атрибута id
, в котором нужно разместить форму, и при необходимости код, который нужно выполнить после отображения платежной формы.HTML
<!--Подключение библиотеки--> <script src="https://yookassa.ru/checkout-widget/v1/checkout-widget.js"></script> <!--HTML-элемент, в котором будет отображаться платежная форма--> <div id="payment-form"></div> <script> //Инициализация виджета. Все параметры обязательные. const checkout = new window.YooMoneyCheckoutWidget({ confirmation_token: 'confirmation-token', //Токен, который перед проведением оплаты нужно получить от ЮKassa return_url: 'https://merchant.site', //Ссылка на страницу завершения оплаты error_callback: function(error) { //Обработка ошибок инициализации } }); //Отображение платежной формы в контейнере checkout.render('payment-form') //После отображения платежной формы метод render возвращает Promise (можно не использовать). .then(() => { //Код, который нужно выполнить после отображения платежной формы. }); </script>
В процессе оплаты виджет может отображать пользователю различные сообщения. Чтобы пользователь мог их прочитать, добавьте на ваш сайт поддержку кодировки UTF-8.
Если на вашей странице оплаты пользователь может изменить заказ, вы можете перезагрузить инициализированный виджет без обновления всей страницы.
Как это выглядит:
- Пользователь переходит к оплате.
- Вы отправляете ЮKassa запрос на создание платежа, получаете токен, инициализируете виджет и отображаете форму на странице оплаты.
- Пользователь что-то меняет в заказе.
- Вы удаляете инициализированный виджет, вызвав метод destroy.
- Вы отправляете ЮKassa запрос на создание платежа, получаете новый токен.
- Вы инициализируете виджет с новым токеном и отображаете форму на странице оплаты.
- Пользователь выбирает способ оплаты, вводит данные, подтверждает платеж.
- Виджет перенаправляет пользователя на страницу завершения оплаты на вашей стороне.
- Вы отображаете нужную информацию, в зависимости от статуса платежа.
Пример использования метода destroy
HTML
<!--Подключение библиотеки--> <script src="https://yookassa.ru/checkout-widget/v1/checkout-widget.js"></script> <!--HTML-элемент, в котором будет отображаться платежная форма--> <div id="payment-form"></div> <script> //Инициализация виджета. Все параметры обязательные. const checkout = new window.YooMoneyCheckoutWidget({ confirmation_token: 'confirmation-token', //Токен, который перед проведением оплаты нужно получить от ЮKassa return_url: 'https://merchant.site', //Ссылка на страницу завершения оплаты error_callback: function(error) { //Обработка ошибок инициализации } }); //Отображение платежной формы в контейнере checkout.render('payment-form') //После отображения платежной формы метод render возвращает Promise (можно не использовать). .then(() => { //Код, который нужно выполнить после отображения платежной формы. }); //Удаление платежной формы из контейнера checkout.destroy(); //Инициализация нового виджета. Все параметры обязательные. const checkoutNew = new window.YooMoneyCheckoutWidget({ confirmation_token: 'confirmation-token', //Токен, который перед проведением оплаты нужно получить от ЮKassa return_url: 'https://merchant.site', //Ссылка на страницу завершения оплаты error_callback: function(error) { //Обработка ошибок инициализации } }); //Отображение платежной формы в контейнере checkoutNew.render('payment-form') //После отображения платежной формы метод render возвращает Promise (можно не использовать). .then(() => { //Код, который нужно выполнить после отображения платежной формы. }); </script>
Чтобы провести платеж:
Если хотите протестировать виджет, создайте платеж для вашего тестового магазина и заплатите одной из тестовых карт. Подробнее о тестировании платежей
Для создания платежа отправьте ЮKassa запрос, передайте в нём данные для аутентификации запроса, ключ идемпотентности, объект
amount
с суммой платежа, объект confirmation
с типом embedded
и, при необходимости, параметр description
с описанием транзакции, которое вы увидите в личном кабинете и при запросе информации о платеже . Также передайте параметр capture
со значением true
. Это значит, что вы получите деньги сразу после оплаты (при значении false
нужная сумма заблокируется на счете пользователя, и после этого вы можете ее списать в удобное вам время).По умолчанию тексты в платежной форме отображаются на русском. Чтобы изменить язык интерфейса на английский или немецкий, передайте в
confirmation
параметр locale
со значением en_US
или de_DE
соответственно.В запросе можно передать любые другие параметры, кроме
payment_method_data
, payment_method_id
, payment_token
, airline
. cURL
PHP
Python
curl https://api.yookassa.ru/v3/payments \ -X POST \ -u <Идентификатор магазина>:<Секретный ключ> \ -H 'Idempotence-Key: <Ключ идемпотентности>' \ -H 'Content-Type: application/json' \ -d '{ "amount": { "value": "2.00", "currency": "RUB" }, "confirmation": { "type": "embedded" }, "capture": true, "description": "Заказ №72" }'
В объекте платежа ЮKassa вернет
confirmation_token
.JSON
{ "id": "22d6d597-000f-5000-9000-145f6df21d6f", "status": "pending", "paid": false, "amount": { "value": "2.00", "currency": "RUB" }, "confirmation": { "type": "embedded", "confirmation_token": "ct-24301ae5-000f-5000-9000-13f5f1c2f8e0" }, "created_at": "2018-07-10T14:25:27.535Z", "description": "Заказ №72", "metadata": {}, "recipient": { "account_id": "100001", "gateway_id": "1000001" }, "refundable": false, "test": false }
Используйте этот токен для создания экземпляра класса
YooMoneyCheckoutWidget
и инициализации виджета.Токен одноразовый, срок действия — 1 час. Если пользователь не оплатит в течение часа, виджет не инициализируется, токен нужно будет запрашивать заново. Если пользователь оплатит и вернется к форме, она отобразится с ошибкой.
Чтобы заново запросить токен, создайте платеж еще раз и инициализируйте виджет с новым токеном.
Когда пользователь введет данные для оплаты и подтвердит платеж, ЮKassa перенаправит его на
return_url
, который вы передадите при инициализации виджета. Вам нужно самостоятельно узнать, как завершился платеж — успехом или неудачей — и отобразить пользователю нужную информацию.Чтобы узнать статус платежа, подождите, когда придет уведомление от ЮKassa, или периодически отправляйте запросы, чтобы получить информацию о платеже .
С помощью виджета ЮKassa вы можете сохранять способ оплаты, чтобы использовать его для автоплатежей, например, для ежемесячной оплаты подписки.
По умолчанию автоплатежи работают только в тестовом магазине. Если хотите использовать их в вашем реальном магазине, напишите менеджеру ЮKassa.
Если вам разрешено использование автоплатежей, вы можете проводить платежи:
Сохранение способа оплаты позволяет привязать карту или кошелек ЮMoney к вашему магазину. С помощью виджета вы можете проводить платежи с безусловным или с условным сохранением способа.
Безусловное сохранение способа оплаты — сохранение способа происходит по умолчанию, пользователь не может на это повлиять. Как это выглядит:
- Вы на сайте предупреждаете пользователя, что сохраните его платежные данные, и рассказываете, как будете их использовать, например, с какой регулярностью вы будете списывать деньги и на какую сумму, как пользователь может отказаться от повторных списаний в вашем магазине. Вы на своей стороне получаете от пользователя согласие на проведение автоплатежей.
- Виджет отображает пользователю только два способа оплаты: произвольной банковской картой или из кошелька ЮMoney. Когда пользователь выберет способ оплаты, виджет ему сообщит, что способ оплаты будет привязан к вашему магазину. При успешной оплате данные карты или кошелька автоматически сохранятся в ЮKassa.
Пример использования: подписка на регулярные платежи.
Платеж с безусловным сохранением способа оплаты
Условное сохранение способа оплаты — сохранение способа происходит по желанию пользователя. Как это выглядит:
- Вы на сайте рассказываете о возможности сохранить платежные данные, о том, как вы будете их использовать и как потом от этого отказаться.
- Виджет отображает пользователю все доступные способы оплаты. Если пользователь выберет произвольную карту или оплату из кошелька ЮMoney, виджет предложит ему сохранить данные для вашего магазина. Если пользователь согласится, при успешной оплате данные способа будут сохранены в ЮKassa, и вы сможете использовать идентификатор сохраненного способа оплаты для последующих платежей. Если не согласится, платеж пройдет без привязки данных к магазину.
Пример использования: привязка платежного средства к магазину для ускорения процесса оплаты при последующих платежах.
Платеж с условным сохранением способа оплаты
cURL
PHP
Python
curl https://api.yookassa.ru/v3/payments \ -X POST \ -u <Идентификатор магазина>:<Секретный ключ> \ -H 'Idempotence-Key: <Ключ идемпотентности>' \ -H 'Content-Type: application/json' \ -d '{ "amount": { "value": "2.00", "currency": "RUB" }, "confirmation": { "type": "embedded" }, "capture": true, "save_payment_method": true, "description": "Заказ №72" }'
Шаг 2. В ответе от ЮKassa получите
confirmation_token
— токен для инициализации виджета.JSON
{ "id": "25564507-000f-5000-9000-19878c91d156", "status": "pending", "paid": false, "amount": { "value": "2.00", "currency": "RUB" }, "confirmation": { "type": "embedded", "confirmation_token": "ct-25564507-000f-5000-9000-19878c91d156" }, "created_at": "2019-11-07T14:59:19.351Z", "description": "Заказ №72", "metadata": {}, "recipient": { "account_id": "100001", "gateway_id": "1000001" }, "refundable": false, "test": false }
Шаг 3. Инициализируйте виджет.
Шаг 4. Далее проводите платеж как обычно.
Если оплата прошла успешно, получите идентификатор сохраненного способа оплаты.
Шаг 1. Создайте платеж, передавать
save_payment_method
не нужно.cURL
PHP
Python
curl https://api.yookassa.ru/v3/payments \ -X POST \ -u <Идентификатор магазина>:<Секретный ключ> \ -H 'Idempotence-Key: <Ключ идемпотентности>' \ -H 'Content-Type: application/json' \ -d '{ "amount": { "value": "2.00", "currency": "RUB" }, "confirmation": { "type": "embedded" }, "capture": true, "description": "Заказ №72" }'
Шаг 2. В ответе от ЮKassa получите
confirmation_token
— токен для инициализации виджета.JSON
{ "id": "25564507-000f-5000-9000-19878c91d156", "status": "pending", "paid": false, "amount": { "value": "2.00", "currency": "RUB" }, "confirmation": { "type": "embedded", "confirmation_token": "ct-2557c659-000f-5000-9000-12714806d854" }, "created_at": "2019-11-07T14:59:19.351Z", "description": "Заказ №72", "metadata": {}, "recipient": { "account_id": "100001", "gateway_id": "1000001" }, "refundable": false, "test": false }
Шаг 3. Инициализируйте виджет.
Шаг 4. Далее проводите платеж как обычно.
Если оплата прошла успешно, получите идентификатор сохраненного способа оплаты.
Шаг 1. Дождитесь, когда пользователь подтвердит оплату, и платеж перейдет в статус
succeeded
(или waiting_for_capture
, если это платеж в две стадии). Чтобы узнать статус платежа, подождите, когда придет уведомление от ЮKassa, или периодически отправляйте запросы, чтобы получить информацию о платеже .Шаг 2. Убедитесь, что способ оплаты сохранен: в объекте платежа значение
payment_method.saved
изменилось на true
.JSON
{ "id": "25564507-000f-5000-9000-19878c91d156", "status": "succeeded", "paid": true, "amount": { "value": "2.00", "currency": "RUB" }, "authorization_details": { "rrn": "10000000000", "auth_code": "000000" }, "captured_at": "2018-07-18T17:20:50.825Z", "created_at": "2018-07-18T17:18:39.345Z", "description": "Заказ №72", "metadata": {}, "payment_method": { "type": "bank_card", "id": "25564507-000f-5000-9000-19878c91d156", "saved": true, "card": { "first6": "555555", "last4": "4444", "expiry_month": "07", "expiry_year": "2022", "card_type": "MasterCard", "issuer_country": "RU", "issuer_name": "Sberbank" }, "title": "Bank card *4444" }, "refundable": true, "refunded_amount": { "value": "0.00", "currency": "RUB" }, "recipient": { "account_id": "100001", "gateway_id": "1000001" }, "test": false }
Шаг 3. Сохраните идентификатор способа оплаты
payment_method.id
. Его нужно будет использовать в качестве идентификатора сохраненного способа оплаты при последующих платежах.Готово!
Теперь вы можете проводить автоплатежи. Проведение платежа сохраненным способом оплаты нужно реализовать самостоятельно.
Вы можете проводить платежи без сохранения способа оплаты. Пользователь сможет оплатить любым доступным способом. Способ оплаты не сохранится.
Чтобы провести платеж без сохранения способа оплаты:
cURL
PHP
Python
curl https://api.yookassa.ru/v3/payments \ -X POST \ -u <Идентификатор магазина>:<Секретный ключ> \ -H 'Idempotence-Key: <Ключ идемпотентности>' \ -H 'Content-Type: application/json' \ -d '{ "amount": { "value": "2.00", "currency": "RUB" }, "confirmation": { "type": "embedded" }, "capture": true, "save_payment_method": false, "description": "Заказ №72" }'
Шаг 2. В ответе от ЮKassa получите
confirmation_token
— токен для инициализации виджета.JSON
{ "id": "25564507-000f-5000-9000-19878c91d156", "status": "pending", "paid": false, "amount": { "value": "2.00", "currency": "RUB" }, "confirmation": { "type": "embedded", "confirmation_token": "ct-25564507-000f-5000-9000-19878c91d156" }, "created_at": "2019-11-07T14:59:19.351Z", "description": "Заказ №72", "metadata": {}, "recipient": { "account_id": "100001", "gateway_id": "1000001" }, "refundable": false, "test": false }
Шаг 3. Инициализируйте виджет.
Шаг 4. Далее проводите платеж как обычно.
По умолчанию в виджете белая платежная форма, а для важных элементов, например кнопки Заплатить, используется акцентный желтый цвет. Такой дизайн помогает пользователю сфокусироваться на главном — какой способ оплаты он выбрал, куда вводит данные и как перейти к оплате.
Виджет можно адаптировать под любой дизайн. Для настройки достаточно задать всего один или два цвета — остальные цвета виджет подберет сам. При необходимости вы можете откорректировать автоматически рассчитанные цвета, передав дополнительные параметры.
Примеры настройки цветовой схемы
Цветовая схема задается при инициализации виджета с помощью объекта
colors
, переданного в объекте customization
. В объекте colors
задаются параметры, влияющие на цвета элементов интерфейса.Можно задать максимум шесть параметров: два базовых и четыре дополнительных. Каждый из базовых параметров отвечает за определенную группу элементов интерфейса. Если передать такой параметр, виджет на его основе рассчитает все нужные цвета. При необходимости вы можете уточнить автоматически подобранные цвета с помощью дополнительных параметров.
Значения цветов необходимо задавать в шестнадцатеричном представлении (HEX), иначе виджет проигнорирует настройки.
Полезное для настройки цветовой схемы:
Выберите, что вы хотите попробовать изменить: цвет кнопки Заплатить или цвет всей формы.
Шаг 1. Добавьте в скрипт для инициализации виджета объект
customization
с объектом colors
и параметром controlPrimary
.HTML
<!--Подключение библиотеки--> <script src="https://yookassa.ru/checkout-widget/v1/checkout-widget.js"></script> <!--HTML-элемент, в котором будет отображаться платежная форма--> <div id="payment-form"></div> <script> //Инициализация виджета. Все параметры обязательные, кроме объекта customization. const checkout = new window.YooMoneyCheckoutWidget({ confirmation_token: 'confirmation-token', //Токен, который перед проведением оплаты нужно получить от ЮKassa return_url: 'https://merchant.site', //Ссылка на страницу завершения оплаты //Настройка виджета customization: { //Настройка цветовой схемы, минимум один параметр, значения цветов в HEX colors: { //Цвет акцентных элементов: кнопка Заплатить, выбранные переключатели, опции и текстовые поля controlPrimary: '#00BF96' //Значение цвета в HEX } }, error_callback: function(error) { //Обработка ошибок инициализации } }); //Отображение платежной формы в контейнере checkout.render('payment-form'); </script>
Шаг 2. Создайте платеж для тестового магазина и инициализируйте виджет.
Пример настроек из Быстрого старта (кнопка Заплатить)
Готово! Кнопка Заплатить и другие акцентные элементы изменили свой цвет.
Это самый простой способ изменить цвет акцентных элементов. Вы можете выбрать другой вариант настройки, если хотите уточнить автоматически рассчитанные цвета или изменить другие элементы интерфейса.
Шаг 1. Добавьте в скрипт для инициализации виджета объект
customization
с объектом colors
и параметрами controlPrimary
и background
.HTML
<!--Подключение библиотеки--> <script src="https://yookassa.ru/checkout-widget/v1/checkout-widget.js"></script> <!--HTML-элемент, в котором будет отображаться платежная форма--> <div id="payment-form"></div> <script> //Инициализация виджета. Все параметры обязательные, кроме объекта customization. const checkout = new window.YooMoneyCheckoutWidget({ confirmation_token: 'confirmation-token', //Токен, который перед проведением оплаты нужно получить от ЮKassa return_url: 'https://merchant.site', //Ссылка на страницу завершения оплаты //Настройка виджета customization: { //Настройка цветовой схемы, минимум один параметр, значения цветов в HEX colors: { //Цвет акцентных элементов: кнопка Заплатить, выбранные переключатели, опции и текстовые поля controlPrimary: '#00BF96', //Значение цвета в HEX //Цвет платежной формы и ее элементов background: '#F2F3F5' //Значение цвета в HEX } }, error_callback: function(error) { //Обработка ошибок инициализации } }); //Отображение платежной формы в контейнере checkout.render('payment-form'); </script>
Шаг 2. Создайте платеж для тестового магазина и инициализируйте виджет.
Пример настроек из Быстрого старта (вся платежная форма)
Готово! Платежная форма и кнопка Заплатить изменили свои цвета.
Это самый простой способ изменить цвета всей платежной формы. Вы можете выбрать другой вариант настройки, если хотите уточнить автоматически рассчитанные цвета или изменить другие элементы интерфейса.
Количество параметров, передаваемых в
colors
, зависит от того, что вы хотите изменить:- Только акцентные элементы: белая платежная форма подходит вашему сайту, а желтые акцентные элементы — нет.
- Только платежная форма: желтые акценты устраивают, но белая форма не подходит (например, у вас на сайте есть темная тема).
- Акцентные элементы и платежная форма: цвета по умолчанию не подходят совсем, нужно поменять цвета всех элементов.
- Только детали: всё в целом устраивает, но нужно изменить какие-то детали, например цвет границ платежной формы.
Акцентные элементы в виджете — это то, что помогает сфокусироваться и призывает к действию: кнопка Заплатить, выбранные переключатели, опции, граница выбранного текстового поля.
На цвет акцентных элементов влияют два параметра:
- controlPrimary(базовый цвет) — цвет фона кнопки Заплатить и других акцентных элементов.
- controlPrimaryContent— цвет текста в кнопке и содержимого акцентных переключателей и опций (например, выставленный флажок).
Чтобы изменить цвет акцентных элементов, достаточно передать только
controlPrimary
. В этом случае виджет автоматически выберет в качестве цвета текста либо черный, либо белый цвет (наиболее контрастный к controlPrimary
).
Параметры, определяющие цвет акцентных элементов — экран выбора способа оплаты
Параметры, определяющие цвет акцентных элементов — экран ввода данных
Рекомендуется для
controlPrimary
выбирать цвет, привлекающий внимание, для controlPrimaryContent
— контрастный цвет, который будет читаться на фоне базового цвета.Рекомендуется начать настройку с базового цвета, а дополнительный цвет использовать при необходимости:
Шаг 1. Добавьте в скрипт для инициализации виджета объект
customization
с объектом colors
и параметром controlPrimary
.JavaScript
customization: { //Настройка цветовой схемы, минимум один параметр, значения цветов в HEX colors: { controlPrimary: '#00BF96' // Базовый цвет кнопки Заплатить и других акцентных элементов // Цвет текста кнопки Заплатить, цвет флажка в переключателе подберется автоматически } },
Шаг 2. Создайте платеж для тестового магазина, инициализируйте виджет и проверьте, как смотрится платежная форма.
Шаг 3. При необходимости уточните автоматически рассчитанный цвет текста в кнопке Заплатить. Для этого добавьте в скрипт параметр
controlPrimaryContent
с нужным цветом и инициализируйте виджет заново (или обновите страницу оплаты).JavaScript
customization: { //Настройка цветовой схемы, минимум один параметр, значения цветов в HEX colors: { controlPrimary: '#00BF96', // Базовый цвет кнопки Заплатить и других акцентных элементов controlPrimaryContent: '#FFFFFF' // Цвет текста кнопки Заплатить, цвет флажка в переключателе } },
Пример настройки цветов акцентных элементов (controlPrimary и controlPrimaryContent)
Готово! Виджет можно использовать для приема платежей от ваших пользователей.
Платежная форма состоит из блоков способов оплаты (кошелек ЮMoney, банковская карта, Сбербанк Онлайн), кнопок Apple Pay, Google Pay, сообщения о принятии оферты и логотипа ЮKassa.
Цвет фона, на котором располагаются элементы, — это цвет страницы оплаты или фона контейнера, в котором размещен виджет (вы изменяете его самостоятельно на странице оплаты). Кнопка Заплатить — акцентный элемент, который настраивается отдельно. На все остальные элементы влияют четыре параметра:
- background(базовый цвет) — цвет фона блоков способов оплаты, цвет сообщений об ошибках и подсказок, внешний вид кнопок Apple Pay, Google Pay и логотипов.
- text— цвет текста.
- border— цвет границ и разделителей.
- controlSecondary— цвет неакцентных элементов интерфейса.
Чтобы изменить цвет платежной формы, достаточно передать только
background
. В этом случае цвет границ, текста и неакцентных элементов виджет рассчитает автоматически.
Параметры, определяющие цвет формы — экран выбора способа оплаты
Параметры, определяющие цвет формы — экран ввода данных
Рекомендуется для
background
выбирать цвет, близкий к цвету фона контейнера, в котором размещен виджет, для text
— контрастный цвет, который будет читаться на фоне платежной формы, на фоне неакцентных элементов и на фоне контейнера. Остальные цвета рекомендуется подбирать так, чтобы они хорошо смотрелись на фоне background
.Кнопки Apple Pay и Google Pay и логотип ЮKassa могут быть только черными или белыми. Внешний вид зависит от параметра
background
. Остальные параметры на них не влияют.Рекомендуется начать настройку с базового цвета, а дополнительные цвета использовать при необходимости:
Шаг 1. Добавьте в скрипт для инициализации виджета объект
customization
с объектом colors
и параметром background
.JavaScript
customization: { //Настройка цветовой схемы, минимум один параметр, значения цветов в HEX colors: { background: '#F2F3F5' // Цвет фона платежной формы //Цвет текста, границ, неакцентных элементов рассчитается автоматически } },
Шаг 2. Создайте платеж для тестового магазина, инициализируйте виджет и проверьте, как смотрится платежная форма.
Шаг 3. При необходимости уточните автоматически рассчитанные цвета текстов, границ или неакцентных элементов. Для этого добавьте в скрипт дополнительные параметры с нужными цветами и инициализируйте виджет заново (или обновите страницу оплаты).
JavaScript
customization: { //Настройка цветовой схемы, минимум один параметр, значения цветов в HEX colors: { background: '#F2F3F5', // Цвет фона платежной формы text: '#222222', // Цвет текста border: '#D4D4D4', // Цвет границ и разделителей controlSecondary: '#AFBDCA' // Цвет неакцентных элементов интерфейса } },
Пример настройки цветов платежной формы (background, text, border, controlSecondary)
Готово! Виджет можно использовать для приема платежей от ваших пользователей.
Если вы хотите поменять все цвета виджета, используйте одновременно параметры для изменения акцентных элементов и платежной формы.
Рекомендуется начать настройку с базовых цветов, а дополнительные цвета использовать при необходимости:
Шаг 1. Добавьте в скрипт для инициализации виджета объект
customization
с объектом colors
и параметрами controlPrimary
и background
.JavaScript
customization: { //Настройка цветовой схемы, минимум один параметр, значения цветов в HEX colors: { background: '#0D182F', // Цвет фона платежной формы controlPrimary: '#00BF96' // Цвет кнопки Заплатить и других акцентных элементов } },
Шаг 2. Создайте платеж для тестового магазина, инициализируйте виджет и проверьте, как смотрится платежная форма.
Шаг 3. При необходимости уточните автоматически рассчитанные цвета. Для этого добавьте в скрипт дополнительные параметры с нужными цветами и инициализируйте виджет заново (или обновите страницу оплаты).
JavaScript
customization: { //Настройка цветовой схемы, минимум один параметр, значения цветов в HEX colors: { background: '#0D182F', // Цвет фона платежной формы controlPrimary: '#00BF96', // Цвет кнопки Заплатить и других акцентных элементов controlPrimaryContent: '#FFFFFF', // Цвет текста кнопки Заплатить controlSecondary: '#366093', // Цвет неакцентных элементов интерфейса border: '#244166', // Цвет границ и разделителей text: '#DBDCE0' // Цвет текста } },
Пример настройки всех цветов (все параметры). Фон контейнера задается отдельно
Готово! Виджет можно использовать для приема платежей от ваших пользователей.
Вы можете задать только дополнительные цвета, например только цвет границ. Если нужно изменить базовые цвета, используйте инструкции по настройке акцентных элементов и платежной формы.
Рекомендуемый порядок настройки:
Шаг 1. Добавьте в скрипт для инициализации виджета объект
customization
с объектом colors
и нужными вам параметрами.Шаг 2. Создайте платеж для тестового магазина, инициализируйте виджет и проверьте, как смотрится платежная форма.
Готово! Виджет можно использовать для приема платежей от ваших пользователей.
Пример точечной настройки виджета
JavaScript
customization: { //Настройка цветовой схемы, минимум один параметр, значения цветов в HEX colors: { controlPrimaryContent: '#0070F0', // Цвет текста кнопки Заплатить border: '#00BF96' // Цвет границ и разделителей } },
Пример точечной настройки виджета (controlPrimaryContent и border)
Описание всех параметров объекте
colors
, которые можно использовать для настройки цветовой схемы.| Параметр | Описание | По умолчанию |
|---|---|---|
| controlPrimary | Цвет фона акцентных элементов: кнопка Заплатить, выбранные переключатели, опции, граница выбранного текстового поля. Рекомендуется использовать яркий цвет, привлекающий внимание | #FFCC00 (желтый) |
| controlPrimaryContent | Цвет текста в кнопке Заплатить и содержимого акцентных переключателей и опций (например, выставленный флажок). Рекомендуется использовать цвет, контрастный к controlPrimary . Если параметр не передан, цвет рассчитывается на основе controlPrimary | #000000 (черный) или #FFFFFF (белый) — выбирается контрастный к controlPrimary |
| background | Цвет фона платежной формы, цвет сообщений об ошибках и подсказок, а также внешний вид кнопок Apple Pay, Google Pay и логотипов. Рекомендуется использовать цвет, близкий к цвету фона контейнера, в котором размещен виджет | #FFFFFF (белый) |
| text | Цвет всех текстов на платежной форме, кроме текстов в кнопке Заплатить и во всплывающих подсказках. Если параметр не передан, цвет рассчитывается на основе background | Контрастный к background |
| border | Цвет границ и разделителей. Если параметр не передан, цвет рассчитывается на основе background | Контрастный к background |
| controlSecondary | Цвет неакцентных элементов интерфейса. Если параметр не передан, цвет рассчитывается на основе background | Контрастный к background |
Виджет поддерживает два режима отображения способов оплаты: все способы или только один.
По умолчанию на платежной форме отображаются все способы оплаты, которые доступны магазину и есть в виджете. Дизайн экрана выбора и порядок отображения способов оплаты определяет виджет. Когда пользователь переходит к оплате, он выбирает нужный ему способ, вводит данные и подтверждает платеж.
Если готовый экран выбора вам не подходит, вы можете его отключить и указать тот способ оплаты, форму которого хотите отобразить пользователю. Этот режим подойдет тем, кто хочет реализовать собственный экран выбора или использовать только один способ оплаты.
Чтобы отобразить форму оплаты конкретным способом, при инициализации виджета передайте объект
customization
с массивом payment_methods
. Значение, которое нужно передать в массиве payment_methods
, зависит от способа оплаты, который вы хотите использовать:Вы можете разместить на странице оплаты несколько экземпляров виджета. В этом случае создать платеж нужно только один раз и инициализировать все экземпляры одним и тем же токеном. Токен будет работать, пока не закончится срок его действия или пока пользователь не подтвердит платеж.
Чтобы отобразить форму для оплаты банковской картой, передайте в
payment_methods
значение bank_card
. Минимальная ширина контейнера для отображения платежной формы — 280 пикселей.JavaScript
<script> //Инициализация виджета. Все параметры обязательные, кроме объекта customization. const checkout = new window.YooMoneyCheckoutWidget({ confirmation_token: 'confirmation-token', //Токен, который перед проведением оплаты нужно получить от ЮKassa return_url: 'https://merchant.site', //Ссылка на страницу завершения оплаты //Настройка виджета customization: { //Выбор способа оплаты для отображения payment_methods: ['bank_card'] }, error_callback: function(error) { //Обработка ошибок инициализации } }); //Отображение платежной формы в контейнере checkout.render('payment-form'); </script>
Чтобы отобразить кнопку для оплаты через Apple Pay, передайте в
payment_methods
значение apple_pay
. Минимальная ширина контейнера для отображения кнопки — 100 пикселей, минимальная высота — 40 пикселей.Кнопка отображается только в браузерах Safari, если пользователь вошел в свой аккаунт на Apple. Если кнопку отобразить нельзя, вы получите ошибку
no_payment_methods_to_display
.Apple Pay нельзя сохранить для повторов платежей. Если при создании платежа передать
save_payment_method
со значением true
, кнопка не отобразится, вы получите ошибку no_payment_methods_to_display
.JavaScript
<script> //Инициализация виджета. Все параметры обязательные, кроме объекта customization. const checkout = new window.YooMoneyCheckoutWidget({ confirmation_token: 'confirmation-token', //Токен, который перед проведением оплаты нужно получить от ЮKassa return_url: 'https://merchant.site', //Ссылка на страницу завершения оплаты //Настройка виджета customization: { //Выбор способа оплаты для отображения payment_methods: ['apple_pay'] }, error_callback: function(error) { //Обработка ошибок инициализации } }); //Отображение платежной формы в контейнере checkout.render('payment-form'); </script>
Чтобы отобразить кнопку для оплаты через Google Pay, передайте в
payment_methods
значение google_pay
. Минимальная ширина контейнера для отображения кнопки — 100 пикселей, минимальная высота — 40 пикселей.Кнопка отображается, только если пользователь вошел в свой аккаунт на Google. Если кнопку отобразить нельзя, вы получите ошибку
no_payment_methods_to_display
.Google Pay нельзя сохранить для повторов платежей. Если при создании платежа передать
save_payment_method
со значением true
, кнопка не отобразится, вы получите ошибку no_payment_methods_to_display
.JavaScript
<script> //Инициализация виджета. Все параметры обязательные, кроме объекта customization. const checkout = new window.YooMoneyCheckoutWidget({ confirmation_token: 'confirmation-token', //Токен, который перед проведением оплаты нужно получить от ЮKassa return_url: 'https://merchant.site', //Ссылка на страницу завершения оплаты //Настройка виджета customization: { //Выбор способа оплаты для отображения payment_methods: ['google_pay'] }, error_callback: function(error) { //Обработка ошибок инициализации } }); //Отображение платежной формы в контейнере checkout.render('payment-form'); </script>
Чтобы отобразить форму для оплаты из кошелька ЮMoney, с привязанных карт и баллами лояльности, передайте в
payment_methods
значение yoo_money
. Минимальная ширина контейнера для отображения платежной формы — 280 пикселей.JavaScript
<script> //Инициализация виджета. Все параметры обязательные, кроме объекта customization. const checkout = new window.YooMoneyCheckoutWidget({ confirmation_token: 'confirmation-token', //Токен, который перед проведением оплаты нужно получить от ЮKassa return_url: 'https://merchant.site', //Ссылка на страницу завершения оплаты //Настройка виджета customization: { //Выбор способа оплаты для отображения payment_methods: ['yoo_money'] }, error_callback: function(error) { //Обработка ошибок инициализации } }); //Отображение платежной формы в контейнере checkout.render('payment-form'); </script>
Чтобы отобразить форму для оплаты через Сбербанк Онлайн, передайте в
payment_methods
значение sberbank
. Минимальная ширина контейнера для отображения платежной формы — 280 пикселей.Сбербанк Онлайн нельзя сохранить для повторов платежей. Если при создании платежа передать
save_payment_method
со значением true
, вы получите ошибку no_payment_methods_to_display
, пользователь увидит сообщение о техническом сбое.JavaScript
<script> //Инициализация виджета. Все параметры обязательные, кроме объекта customization. const checkout = new window.YooMoneyCheckoutWidget({ confirmation_token: 'confirmation-token', //Токен, который перед проведением оплаты нужно получить от ЮKassa return_url: 'https://merchant.site', //Ссылка на страницу завершения оплаты //Настройка виджета customization: { //Выбор способа оплаты для отображения payment_methods: ['sberbank'] }, error_callback: function(error) { //Обработка ошибок инициализации } }); //Отображение платежной формы в контейнере checkout.render('payment-form'); </script>
Вы можете передать два типа комбинаций способов оплаты: Apple Pay и Google Pay и банковская карта с Apple Pay и Google Pay. В этом случае способы оплаты отобразятся друг под другом.
Чтобы использовать комбинацию способов оплаты, перечислите их коды через запятую.
Одновременно можно передавать только коды
bank_card
, apple_pay
и google_pay
. Если передать комбинацию из других способов оплаты, виджет вернет ошибку invalid_combination_of_payment_methods
.JavaScript
<script> //Инициализация виджета. Все параметры обязательные, кроме объекта customization. const checkout = new window.YooMoneyCheckoutWidget({ confirmation_token: 'confirmation-token', //Токен, который перед проведением оплаты нужно получить от ЮKassa return_url: 'https://merchant.site', //Ссылка на страницу завершения оплаты //Настройка виджета customization: { //Выбор способа оплаты для отображения payment_methods: ['bank_card', 'apple_pay', 'google_pay'] }, error_callback: function(error) { //Обработка ошибок инициализации } }); //Отображение платежной формы в контейнере checkout.render('payment-form'); </script>
Описание параметров, которые передаются при инициализации виджета, и описание ошибок, связанных с инициализацией.
Описание параметров, которые необходимо передать в экземпляр класса
YooMoneyCheckoutWidget
на странице оплаты для инициализации виджета.| Параметр | Тип | Обязательность | Описание |
|---|---|---|---|
| confirmation_token | string | Обязательный | Токен ЮKassa для инициализации виджета. Чтобы получить токен, нужно создать платеж |
| return_url | string | Обязательный | Адрес страницы, на которую пользователь вернется после завершения оплаты. Адрес должен быть абсолютным (с указанием протокола и домена сайта). Пример: https://merchant-web-site.com/orderid-1111 |
| customization | object | Необязательный | Настройка платежной формы. Сейчас можно настроить цветовую схему и отображение способов оплаты. |
| colors | object | Необязательный | Передается в customization . Настройка цветовой схемы. В объекте передаются цвета, которые нужно изменить в интерфейсе платежной формы |
| payment_methods | array | Необязательный | Передается в customization .Настройка отображения способов оплаты. Возможные значения:
Одновременно можно передать только любую комбинацию способов оплаты bank_card , apple_pay , google_pay . |
Если инициализация виджета закончилась неудачей, ЮKassa передаст в callback-функцию код ошибки.
| Код ошибки | Описание |
|---|---|
internal_service_error | При создании платежа возникла ошибка. Повторите инициализацию виджета |
invalid_combination_of_payment_methods | Недопустимое сочетание способов оплаты в payment_methods объекта customization . Одновременно можно передавать только apple_pay , google_pay и bank_card (любое их сочетание). |
invalid_payment_methods | Некорректное значение payment_methods объекта customization . В массиве можно передать коды только тех способов оплаты, которые поддерживает виджет. Если отображаете несколько способов, их коды нужно перечислять через запятую. |
invalid_return_url | Некорректный URL возврата. При инициализации виджета передайте в return_url абсолютный URL страницы завершения оплаты, указав в нем протокол и домен вашего сайта |
invalid_token | Неверный токен. Для получения токена создайте платеж |
no_payment_methods_to_display | Отсутствуют способы оплаты для отображения: например, вы не можете принимать платежи выбранным способом или выбранный способ оплаты нельзя сохранить для автоплатежей (если вы пытаетесь это сделать). При инициализации виджета передайте в payment_methods другой способ оплаты |
return_url_required | URL возврата не передан. При инициализации виджета передайте return_url |
token_expired | Истек срок действия токена. Для получения нового токена создайте платеж |
token_required | Токен не передан. При инициализации виджета передайте confirmation_token |