Виджет ЮKassa
Виджет ЮKassa позволяет встроить на сайт готовую платежную форму. Пользователю будет доступно несколько способов оплаты: кошелек ЮMoney и привязанные к нему банковские карты, произвольная банковская карта, Apple Pay, Google Pay и Сбербанк Онлайн. С помощью виджета пользователь сможет сохранить в вашем магазине банковскую карту или кошелек ЮMoney для автоплатежей.
Платежная форма виджета ЮKassa
Платежная форма автоматически подстраивается под размеры устройства пользователя, проверяет вводимые данные и подсказывает пользователю, если что-то введено некорректно. Можно настроить язык интерфейса и цветовую схему платежной формы.
Чтобы принять платеж с помощью виджета, достаточно создать платеж по API ЮKassa, инициализировать виджет и отобразить форму на странице оплаты.
Для интеграции:
  1. Ознакомьтесь со сценарием проведения платежа в виджете.
  2. Настройте способы оплаты.
  3. Подготовьте страницу оплаты.
  4. Реализуйте проведение платежей.
  5. При необходимости реализуйте проведение автоплатежей.
  6. При необходимости настройте цветовую схему виджета.
  7. Настройте обработку ошибок инициализации виджета.
 
Сценарий проведения платежа
  1. Пользователь переходит к оплате.
  2. Вы отправляете ЮKassa запрос на создание платежа.
  3. ЮKassa возвращает вам созданный объект платежа с токеном для инициализации виджета.
  4. Вы инициализируете виджет и отображаете форму на странице оплаты.
  5. Пользователь выбирает способ оплаты, вводит данные.
  6. При необходимости виджет перенаправляет пользователя на страницу подтверждения платежа или отображает всплывающее окно (например, для аутентификации по 3-D Secure).
  7. Пользователь подтверждает платеж.
  8. Виджет перенаправляет пользователя на страницу завершения оплаты на вашей стороне.
  9. Вы отображаете нужную информацию, в зависимости от статуса платежа.
Готово!
 
Настройка способов оплаты
Виджет поддерживает следующие способы оплаты:
  • кошелек ЮMoney и привязанные к нему карты,
  • произвольная банковская карта,
  • Apple Pay,
  • Google Pay,
  • Сбербанк Онлайн.
 
Общие настройки
По умолчанию доступна оплата кошельком ЮMoney и с привязанных карт. Уточните у менеджера ЮKassa, какие еще способы оплаты вам разрешены.
Чтобы в виджете работала оплата с помощью Apple Pay и Google Pay, ваш сайт должен использовать HTTPS и действующий TLS/SSL-сертификат (минимальная версия — TLS v1.2). Для подключения Apple Pay выполните дополнительные настройки.
 
Подключение 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.
 
Перезагрузка виджета
Если на вашей странице оплаты пользователь может изменить заказ, вы можете перезагрузить инициализированный виджет без обновления всей страницы.
Как это выглядит:
  1. Пользователь переходит к оплате.
  2. Вы отправляете ЮKassa запрос на создание платежа, получаете токен, инициализируете виджет и отображаете форму на странице оплаты.
  3. Пользователь что-то меняет в заказе.
  4. Вы удаляете инициализированный виджет, вызвав метод
    destroy
    .
  5. Вы отправляете ЮKassa запрос на создание платежа, получаете новый токен.
  6. Вы инициализируете виджет с новым токеном и отображаете форму на странице оплаты.
  7. Пользователь выбирает способ оплаты, вводит данные, подтверждает платеж.
  8. Виджет перенаправляет пользователя на страницу завершения оплаты на вашей стороне.
  9. Вы отображаете нужную информацию, в зависимости от статуса платежа.
Пример использования метода 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>
 
Проведение платежа
Чтобы провести платеж:
  1. Создайте платеж в ЮKassa
  2. Инициализируйте виджет
  3. Завершите оплату
Если хотите протестировать виджет, создайте платеж для вашего тестового магазина и заплатите одной из тестовых карт. Подробнее о тестировании платежей
 
Шаг 1. Создайте платеж
Для создания платежа отправьте Ю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"
      }'
 
Шаг 2. Инициализируйте виджет
В объекте платежа  Ю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 час. Если пользователь не оплатит в течение часа, виджет не инициализируется, токен нужно будет запрашивать заново. Если пользователь оплатит и вернется к форме, она отобразится с ошибкой.
Чтобы заново запросить токен, создайте платеж еще раз и инициализируйте виджет с новым токеном.
 
Шаг 3. Завершите оплату
Когда пользователь введет данные для оплаты и подтвердит платеж, ЮKassa перенаправит его на 
return_url
, который вы передадите при инициализации виджета. Вам нужно самостоятельно узнать, как завершился платеж — успехом или неудачей — и отобразить пользователю нужную информацию.
Чтобы узнать статус платежа, подождите, когда придет уведомление от ЮKassa, или периодически отправляйте запросы, чтобы получить информацию о платеже .
 
Сохранение способа оплаты для автоплатежей
С помощью виджета ЮKassa вы можете сохранять способ оплаты, чтобы использовать его для автоплатежей, например, для ежемесячной оплаты подписки.
По умолчанию автоплатежи работают только в тестовом магазине. Если хотите использовать их в вашем реальном магазине, напишите менеджеру ЮKassa.
Если вам разрешено использование автоплатежей, вы можете проводить платежи:
 
Платеж с сохранением способа оплаты
Сохранение способа оплаты позволяет привязать карту или кошелек ЮMoney к вашему магазину. С помощью виджета вы можете проводить платежи с безусловным или с условным сохранением способа.
Безусловное сохранение способа оплаты — сохранение способа происходит по умолчанию, пользователь не может на это повлиять. Как это выглядит:
  1. Вы на сайте предупреждаете пользователя, что сохраните его платежные данные, и рассказываете, как будете их использовать, например, с какой регулярностью вы будете списывать деньги и на какую сумму, как пользователь может отказаться от повторных списаний в вашем магазине. Вы на своей стороне получаете от пользователя согласие на проведение автоплатежей.
  2. Виджет отображает пользователю только два способа оплаты: произвольной банковской картой или из кошелька ЮMoney. Когда пользователь выберет способ оплаты, виджет ему сообщит, что способ оплаты будет привязан к вашему магазину. При успешной оплате данные карты или кошелька автоматически сохранятся в ЮKassa.
Пример использования: подписка на регулярные платежи.
Платеж с безусловным сохранением способа оплаты
Условное сохранение способа оплаты — сохранение способа происходит по желанию пользователя. Как это выглядит:
  1. Вы на сайте рассказываете о возможности сохранить платежные данные, о том, как вы будете их использовать и как потом от этого отказаться.
  2. Виджет отображает пользователю все доступные способы оплаты. Если пользователь выберет произвольную карту или оплату из кошелька ЮMoney, виджет предложит ему сохранить данные для вашего магазина. Если пользователь согласится, при успешной оплате данные способа будут сохранены в ЮKassa, и вы сможете использовать идентификатор сохраненного способа оплаты для последующих платежей. Если не согласится, платеж пройдет без привязки данных к магазину.
Пример использования: привязка платежного средства к магазину для ускорения процесса оплаты при последующих платежах.
Платеж с условным сохранением способа оплаты
 
Платеж с безусловным сохранением способа оплаты
Шаг 1. Создайте платеж и передайте в нём
save_payment_method
со значением
true
.
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
}
Шаг 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
}
Шаг 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
. Его нужно будет использовать в качестве идентификатора сохраненного способа оплаты при последующих платежах.
Готово!
Теперь вы можете проводить автоплатежи. Проведение платежа сохраненным способом оплаты нужно реализовать самостоятельно.
 
Платеж без сохранения способа оплаты
Вы можете проводить платежи без сохранения способа оплаты. Пользователь сможет оплатить любым доступным способом. Способ оплаты не сохранится.
Чтобы провести платеж без сохранения способа оплаты:
Шаг 1. Создайте платеж и передайте в нём
save_payment_method
со значением
false
.
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
}
Шаг 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
Чтобы отобразить кнопку для оплаты через 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
Чтобы отобразить кнопку для оплаты через 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
Чтобы отобразить форму для оплаты из кошелька Ю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_tokenstringОбязательныйТокен ЮKassa для инициализации виджета. Чтобы получить токен, нужно создать платеж
return_urlstringОбязательныйАдрес страницы, на которую пользователь вернется после завершения оплаты. Адрес должен быть абсолютным (с указанием протокола и домена сайта). Пример:
https://merchant-web-site.com/orderid-1111
customizationobjectНеобязательныйНастройка платежной формы. Сейчас можно настроить цветовую схему и отображение способов оплаты.
colorsobjectНеобязательныйПередается в 
customization
.
Настройка цветовой схемы. В объекте передаются цвета, которые нужно изменить в интерфейсе платежной формы
payment_methodsarrayНеобязательный
Передается в 
customization
.
  • apple_pay
     — Apple Pay;
  • google_pay
     — Google Pay;
  • bank_card
     — банковская карта;
  • yoo_money
     — ЮMoney (кошелек, привязанные карты и баллы лояльности);
  • sberbank
     — Сбербанк Онлайн.
Одновременно можно передать только любую комбинацию способов оплаты
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
 
Что почитать еще
Быстрый стартПроведение платежейВходящие уведомленияАвтоплатежиCheckout.js