Виджет ЮKassa позволяет встроить на сайт готовую платежную форму. Пользователю будет доступно несколько способов оплаты: кошелек ЮMoney и привязанные к нему банковские карты, произвольная банковская карта, Apple Pay, Google Pay и Сбербанк Онлайн. С помощью виджета пользователь сможет сохранить в вашем магазине банковскую карту или кошелек ЮMoney для автоплатежей.

Платежная форма виджета ЮKassa
Платежная форма автоматически подстраивается под размеры устройства пользователя, проверяет вводимые данные и подсказывает пользователю, если что-то введено некорректно. Можно настроить язык интерфейса и цветовую схему платежной формы.
Чтобы принять платеж с помощью виджета, достаточно создать платеж по API ЮKassa, инициализировать виджет и отобразить форму на странице оплаты.
Для интеграции:
- Ознакомьтесь со сценарием проведения платежа в виджете.
- Настройте способы оплаты.
- Подготовьте страницу оплаты.
- Реализуйте проведение платежей.
- При необходимости настройте способ прохождения аутентификации по 3-D Secure.
- При необходимости реализуйте проведение автоплатежей.
- При необходимости настройте цветовую схему виджета.
- Настройте обработку ошибок инициализации виджета.
- Пользователь переходит к оплате.
- Вы отправляете Ю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. Скачайте файл merchant.ru.yoomoney и разместите его на своем сайте по адресу:
https://<домен вашего сайта>/.well-known/apple-developer-merchantid-domain-association
Путь к файлу должен быть строго таким — с точкой и дефисами. Точка в названии означает, что это скрытая папка.
Шаг 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(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(error) { //Обработка ошибок инициализации } }); //Отображение платежной формы в контейнере checkout.render('payment-form') //После отображения платежной формы метод render возвращает Promise (можно не использовать). .then(() => { //Код, который нужно выполнить после отображения платежной формы. }); //Удаление платежной формы из контейнера checkout.destroy(); //Инициализация нового виджета. Все параметры обязательные. const checkoutNew = new window.YooMoneyCheckoutWidget({ confirmation_token: 'confirmation-token', //Токен, который перед проведением оплаты нужно получить от Яндекс.Кассы return_url: 'https://merchant.site', //Ссылка на страницу завершения оплаты error_callback(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. Далее проводите платеж как обычно.
При оплате банковской картой пользователю обычно нужно подтвердить платеж — пройти аутентификацию по 3-D Secure. Для этого он вводит на странице эмитента специальный код из смс. Если всё хорошо, платеж проходит, если нет, платеж отменяется.
В виджете вы можете управлять тем, где пользователь будет проходить проверку — на отдельной странице или во всплывающем окне.
Аутентификация на отдельной странице (используется по умолчанию) — для прохождения аутентификации пользователь покидает ваш сайт: виджет перенаправляет его со страницы оплаты на страницу эмитента. После проверки эмитент перенаправляет пользователя на страницу завершения оплаты на вашей стороне.
Пример аутентификации на отдельной странице
Аутентификация во всплывающем окне — пользователь проходит аутентификацию, оставаясь на вашем сайте: виджет на странице оплаты отображает всплывающее окно со страницей эмитента. После проверки эмитент перенаправляет пользователя на страницу завершения оплаты на вашей стороне.
Пример аутентификации во всплывающем окне
Чтобы настроить прохождение аутентификации по 3-D Secure:
- Ознакомьтесь с общим сценарием прохождения проверки.
- Выберите способ прохождения аутентификации и настройте виджет.
- Протестируйте выбранный способ.
Аутентификация при оплате банковской картой проходит следующим образом:
- Пользователь в платежной форме виджета вводит данные банковской карты и нажимает Заплатить.
- Виджет перенаправляет пользователя на страницу эмитента или отображает всплывающее окно.
- Пользователь проходит проверку.
- Эмитент сообщает ЮKassa результат прохождения проверки.
- Эмитент перенаправляет пользователя на страницу завершения оплаты — return_url, который вы указали при инициализации виджета.
- Вы узнаёте у ЮKassa результат проверки и отображаете пользователю нужную информацию.
Пользователь может прервать прохождение аутентификации, например если закроет страницу или всплывающее окно. Если после этого он захочет вернуться на страницу оплаты, заново создайте платеж, получите токен и инициализируйте виджет. Старый токен работать не будет — связанный с ним платеж останется в статусе
pending
(ожидает оплаты) до окончания действия токена, а после автоматически перейдет в статус canceled
(отменен).Если пользователь не прошел проверку (ввел неправильный код), платеж отменится и перейдет в статус
canceled
, в причинах отмены будет указано, что не пройдена аутентификация по 3-D Secure.Выберите способ прохождения аутентификации по 3-D Secure:
Этот способ прохождения аутентификации используется в виджете по умолчанию.
Чтобы пользователь проходил аутентификацию по 3-D Secure на отдельной странице, при инициализации виджета передайте параметр
embedded_3ds
со значением false
.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', //Ссылка на страницу завершения оплаты embedded_3ds: false, // Способ прохождения аутентификации 3-D Secure — на отдельной странице. error_callback(error) { //Обработка ошибок инициализации } }); //Отображение платежной формы в контейнере checkout.render('payment-form'); </script>
Если параметр
embedded_3ds
не передать, то пользователь также будет проходить аутентификацию на отдельной странице.Если пользователь в процессе аутентификации уйдет со страницы эмитента, например закроет ее или вернется на страницу оплаты, платеж прервется. Если пользователь захочет возобновить процесс оплаты, заново создайте платеж, инициализируйте виджет и отобразите платежную форму.
Чтобы пользователь проходил аутентификацию по 3-D Secure во всплывающем окне, при инициализации виджета передайте параметр
embedded_3ds
со значением true
.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', //Ссылка на страницу завершения оплаты embedded_3ds: true, // Способ прохождения аутентификации 3-D Secure — во всплывающем окне error_callback(error) { //Обработка ошибок инициализации } }); //Отображение платежной формы в контейнере checkout.render('payment-form'); </script>
Размеры всплывающего окна:
- максимальная ширина — 600 пикселей,
- максимальная высота — 800 пикселей.
На мобильных устройствах всплывающее окно отображается на весь экран.
Если пользователь закроет всплывающее окно или уйдет со страницы оплаты, платеж прервется. При попытке закрыть всплывающее окно виджет предупредит пользователя, что оплата прервется и придется начинать заново. Если пользователь подтвердит действие, всплывающее окно закроется, на странице оплаты вместо платежной формы отобразится сообщение, что процесс прерван.
Сообщение на странице оплаты после закрытия всплывающего окна
Если пользователь захочет вернуться к оплате, заново создайте платеж, инициализируйте виджет и отобразите платежную форму.
Чтобы в браузере корректно отображались все сообщения, добавьте на ваш сайт поддержку кодировки UTF-8.
Рекомендации по проверке прохождения аутентификации по 3-D Secure:
- Проверьте успешный сценарий.
- Проверьте неуспешный сценарий (пользователь не прошел проверку).
- Проверьте прерывание оплаты при прохождении аутентификации: уход со страницы эмитента или ее закрытие, закрытие всплывающего окна и страницы оплаты.
Вы можете проверить успешные и неуспешные сценарии с помощью тестовых банковских карт (карты работают только для вашего тестового магазина).
По умолчанию в виджете белая платежная форма, а для важных элементов, например кнопки Заплатить, используется акцентный желтый цвет. Такой дизайн помогает пользователю сфокусироваться на главном — какой способ оплаты он выбрал, куда вводит данные и как перейти к оплате.
Виджет можно адаптировать под любой дизайн. Для настройки достаточно задать всего один или два цвета — остальные цвета виджет подберет сам. При необходимости вы можете откорректировать автоматически рассчитанные цвета, передав дополнительные параметры.

Примеры настройки цветовой схемы
Цветовая схема задается при инициализации виджета с помощью объекта
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(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(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 |
Описание параметров, которые передаются при инициализации виджета, и описание ошибок, связанных с инициализацией.
Описание параметров, которые необходимо передать в экземпляр класса
YooMoneyCheckoutWidget
на странице оплаты для инициализации виджета.Параметр | Тип | Обязательность | Описание |
---|---|---|---|
confirmation_token | string | Обязательный | Токен ЮKassa для инициализации виджета. Чтобы получить токен, нужно создать платеж |
return_url | string | Обязательный | Адрес страницы, на которую пользователь вернется после завершения оплаты. Адрес должен быть абсолютным (с указанием протокола и домена сайта). Пример: https://merchant-web-site.com/orderid-1111 |
3ds_embedded | boolean | Необязательный | Способ прохождения аутентификации по 3-D Secure: true — во всплывающем окне, false — на отдельной странице. Значение по умолчанию: false |
customization | object | Необязательный | Настройка платежной формы. Сейчас доступна только настройка цветовой схемы |
colors | object | Необязательный | Передается в customization . Настройка цветовой схемы. Перечень параметров, которые можно передать в colors |
Если инициализация виджета закончилась неудачей, ЮKassa передаст в callback-функцию код ошибки.
Код ошибки | Описание |
---|---|
internal_service_error | При создании платежа возникла ошибка. Повторите инициализацию виджета |
invalid_return_url | Некорректный URL возврата. При инициализации виджета передайте в return_url абсолютный URL страницы завершения оплаты, указав в нем протокол и домен вашего сайта |
invalid_token | Неверный токен. Для получения токена создайте платеж |
return_url_required | URL возврата не передан. При инициализации виджета передайте return_url |
token_expired | Истек срок действия токена. Для получения нового токена создайте платеж |
token_required | Токен не передан. При инициализации виджета передайте confirmation_token |