Виджет Яндекс.Кассы
Виджет Яндекс.Кассы позволяет встроить на сайт готовую платежную форму. Пользователю будет доступно несколько способов оплаты: кошелек в Яндекс.Деньгах и привязанные к нему банковские карты, произвольная банковская карта, Apple Pay, Google Pay и Сбербанк Онлайн. С помощью виджета пользователь сможет сохранить в вашем магазине банковскую карту или кошелек в Яндекс.Деньгах для автоплатежей.
Платежная форма виджета Яндекс.Кассы
Платежная форма автоматически подстраивается под размеры устройства пользователя, проверяет вводимые данные и подсказывает пользователю, если что-то введено некорректно. Можно настроить язык интерфейса и цветовую схему платежной формы.
Чтобы принять платеж с помощью виджета, достаточно создать платеж по API Яндекс.Кассы, инициализировать виджет и отобразить форму на странице оплаты.
Для интеграции:
  1. Ознакомьтесь со сценарием проведения платежа в виджете.
  2. Настройте способы оплаты.
  3. Подготовьте страницу оплаты.
  4. Реализуйте проведение платежей.
  5. При необходимости настройте способ прохождения аутентификации по 3-D Secure.
  6. При необходимости реализуйте проведение автоплатежей.
  7. При необходимости настройте цветовую схему виджета.
  8. Настройте обработку ошибок инициализации виджета.
 Сценарий проведения платежа
  1. Пользователь переходит к оплате.
  2. Вы отправляете Яндекс.Кассе запрос на создание платежа.
  3. Яндекс.Касса возвращает вам созданный объект платежа с токеном для инициализации виджета.
  4. Вы инициализируете виджет и отображаете форму на странице оплаты.
  5. Пользователь выбирает способ оплаты, вводит данные.
  6. При необходимости виджет перенаправляет пользователя на страницу подтверждения платежа (например, для аутентификации по 3-D Secure).
  7. Пользователь подтверждает платеж.
  8. Виджет перенаправляет пользователя на страницу завершения оплаты на вашей стороне.
  9. Вы отображаете нужную информацию, в зависимости от статуса платежа.
Готово!
 Настройка способов оплаты
Виджет поддерживает следующие способы оплаты:
  • кошелек в Яндекс.Деньгах и привязанные к нему карты,
  • произвольная банковская карта,
  • Apple Pay,
  • Google Pay,
  • Сбербанк Онлайн.
Кошельком в Яндекс.Деньгах и с привязанных к нему карт может оплатить только пользователь, авторизованный на Яндексе.
 Общие настройки
По умолчанию доступна оплата кошельком в Яндекс.Деньгах и с привязанных карт. Уточните у менеджера Яндекс.Кассы, какие еще способы оплаты вам разрешены.
Чтобы в виджете работала оплата с помощью Apple Pay и Google Pay, ваш сайт должен использовать HTTPS и действующий TLS/SSL-сертификат (минимальная версия — TLS v1.2). Для подключения Apple Pay выполните дополнительные настройки.
 Подключение Apple Pay
Шаг 1. Сообщите вашему менеджеру Яндекс.Кассы адрес сайта, на котором будет размещаться виджет.
Шаг 2. Скачайте файл merchant.ru.yandex.kassa и разместите его на своем сайте по адресу:
https://<домен вашего сайта>/.well-known/apple-developer-merchantid-domain-association
Путь к файлу должен быть строго таким — с точкой и дефисами. Точка в названии означает, что это скрытая папка.
Шаг 3. Чтобы оплата с помощью Apple Pay всегда была доступна в виджете, обновляйте TLS/SSL-сертификат не позднее, чем за 8 дней до окончания его срока действия.
 Подготовка страницы оплаты
Для приема платежей подготовьте страницу оплаты: подключите библиотеку и разместите виджет.
Шаг 1. Подключите скрипт. Библиотека будет доступна в глобальной области видимости под именем
YandexCheckout
.
Шаг 2. На страницу оплаты добавьте HTML-элемент, в котором хотите разместить форму. Задайте для данного элемента атрибут
id
.
Шаг 3. Для инициализации виджета создайте новый экземпляр класса
YandexCheckout
и передайте в него
confirmation_token
, который нужно получить в Яндекс.Кассе перед проведением платежа,
return_url
, на который пользователь вернется после оплаты, и callback-функцию, которая будет принимать код ошибки. При необходимости настройте цветовую схему.
confirmation_token
нужно получать в Яндекс.Кассе для каждого платежа.
Шаг 4. Чтобы отобразить платежную форму, вызовите метод
render
. Передайте в него значение атрибута
id
, в котором нужно разместить форму.
HTML
<!--Подключение библиотеки-->
<script src="https://kassa.yandex.ru/checkout-ui/v2.js"></script>

<!--HTML-элемент, в котором будет отображаться платежная форма-->
<div id="payment-form"></div>

<script>
//Инициализация виджета. Все параметры обязательные.
const checkout = new window.YandexCheckout({
    confirmation_token: 'confirmation-token', //Токен, который перед проведением оплаты нужно получить от Яндекс.Кассы
    return_url: 'https://merchant.site', //Ссылка на страницу завершения оплаты
    error_callback(error) {
        //Обработка ошибок инициализации
    }
});

//Отображение платежной формы в контейнере
checkout.render('payment-form');
</script>
В процессе оплаты виджет может отображать пользователю различные сообщения. Чтобы пользователь мог их прочитать, добавьте на ваш сайт поддержку кодировки UTF-8.
 Проведение платежа
Чтобы провести платеж:
  1. Создайте платеж в Яндекс.Кассе
  2. Инициализируйте виджет
  3. Завершите оплату
Если хотите протестировать виджет, создайте платеж для вашего тестового магазина и заплатите одной из тестовых карт. Подробнее о тестировании платежей
 Шаг 1. Создайте платеж
Для создания платежа отправьте Яндекс.Кассе запрос, передайте в нём данные для аутентификации запроса, ключ идемпотентности, объект
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://payment.yandex.net/api/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. Инициализируйте виджет
В объекте платежа  Яндекс.Касса вернет
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
}
Используйте этот токен для создания экземпляра класса
YandexCheckout
и инициализации виджета.
Токен одноразовый, срок действия — 1 час. Если пользователь не оплатит в течение часа, виджет не инициализируется, токен нужно будет запрашивать заново. Если пользователь оплатит и вернется к форме, она отобразится с ошибкой.
Чтобы заново запросить токен, создайте платеж еще раз и инициализируйте виджет с новым токеном.
 Шаг 3. Завершите оплату
Когда пользователь введет данные для оплаты и подтвердит платеж, Яндекс.Касса перенаправит его на 
return_url
, который вы передадите при инициализации виджета. Вам нужно самостоятельно узнать, как завершился платеж — успехом или неудачей — и отобразить пользователю нужную информацию.
Чтобы узнать статус платежа, подождите, когда придет уведомление от Яндекс.Кассы, или периодически отправляйте запросы, чтобы получить информацию о платеже .
 Сохранение способа оплаты для автоплатежей
С помощью виджета Яндекс.Кассы вы можете сохранять способ оплаты, чтобы использовать его для автоплатежей, например, для ежемесячной оплаты подписки.
По умолчанию автоплатежи работают только в тестовом магазине. Если хотите использовать их в вашем реальном магазине, напишите менеджеру Яндекс.Кассы.
Если вам разрешено использование автоплатежей, вы можете проводить платежи:
 Платеж с сохранением способа оплаты
Сохранение способа оплаты позволяет привязать карту или кошелек в Яндекс.Деньгах к вашему магазину. С помощью виджета вы можете проводить платежи с безусловным или с условным сохранением способа.
Безусловное сохранение способа оплаты — сохранение способа происходит по умолчанию, пользователь не может на это повлиять. Как это выглядит:
  1. Вы на сайте предупреждаете пользователя, что сохраните его платежные данные, и рассказываете, как будете их использовать, например, с какой регулярностью вы будете списывать деньги и на какую сумму, как пользователь может отказаться от повторных списаний в вашем магазине. Вы на своей стороне получаете от пользователя согласие на проведение автоплатежей.
  2. Виджет отображает пользователю только два способа оплаты: произвольной банковской картой или из кошелька в Яндекс.Деньгах (если пользователь авторизован на Яндексе). Когда пользователь выберет способ оплаты, виджет ему сообщит, что способ оплаты будет привязан к вашему магазину. При успешной оплате данные карты или кошелька автоматически сохранятся в Яндекс.Кассе.
Пример использования: подписка на регулярные платежи.
Платеж с безусловным сохранением способа оплаты
Условное сохранение способа оплаты — сохранение способа происходит по желанию пользователя. Как это выглядит:
  1. Вы на сайте рассказываете о возможности сохранить платежные данные, о том, как вы будете их использовать и как потом от этого отказаться.
  2. Виджет отображает пользователю все доступные способы оплаты. Если пользователь выберет произвольную карту или оплату из кошелька в Яндекс.Деньгах, виджет предложит ему сохранить данные для вашего магазина. Если пользователь согласится, при успешной оплате данные способа будут сохранены в Яндекс.Кассе, и вы сможете использовать идентификатор сохраненного способа оплаты для последующих платежей. Если не согласится, платеж пройдет без привязки данных к магазину.
Пример использования: привязка платежного средства к магазину для ускорения процесса оплаты при последующих платежах.
Платеж с условным сохранением способа оплаты
 Платеж с безусловным сохранением способа оплаты
Шаг 1. Создайте платеж и передайте в нём
save_payment_method
со значением
true
.
cURL
PHP
Python
curl https://payment.yandex.net/api/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. В ответе от Яндекс.Кассы получите
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://payment.yandex.net/api/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. В ответе от Яндекс.Кассы получите
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
, если это платеж в две стадии). Чтобы узнать статус платежа, подождите, когда придет уведомление от Яндекс.Кассы, или периодически отправляйте запросы, чтобы получить информацию о платеже .
Шаг 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://payment.yandex.net/api/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. В ответе от Яндекс.Кассы получите
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. Далее проводите платеж как обычно.
 Аутентификация по 3-D Secure при оплате картой
При оплате банковской картой пользователю обычно нужно подтвердить платеж — пройти аутентификацию по 3-D Secure. Для этого он вводит на странице эмитента специальный код из смс. Если всё хорошо, платеж проходит, если нет, платеж отменяется.
В виджете вы можете управлять тем, где пользователь будет проходить проверку — на отдельной странице или во всплывающем окне.
Аутентификация на отдельной странице (используется по умолчанию) — для прохождения аутентификации пользователь покидает ваш сайт: виджет перенаправляет его со страницы оплаты на страницу эмитента. После проверки эмитент перенаправляет пользователя на страницу завершения оплаты на вашей стороне.
Пример аутентификации на отдельной странице
Аутентификация во всплывающем окне — пользователь проходит аутентификацию, оставаясь на вашем сайте: виджет на странице оплаты отображает всплывающее окно со страницей эмитента. После проверки эмитент перенаправляет пользователя на страницу завершения оплаты на вашей стороне.
Пример аутентификации во всплывающем окне
Чтобы настроить прохождение аутентификации по 3-D Secure:
 Общий сценарий прохождения аутентификации
Аутентификация при оплате банковской картой проходит следующим образом:
  1. Пользователь в платежной форме виджета вводит данные банковской карты и нажимает Заплатить.
  2. Виджет перенаправляет пользователя на страницу эмитента или отображает всплывающее окно.
  3. Пользователь проходит проверку.
  4. Эмитент сообщает Яндекс.Кассе результат прохождения проверки.
  5. Эмитент перенаправляет пользователя на страницу завершения оплаты —
    return_url
    , который вы указали при инициализации виджета.
  6. Вы узнаёте у Яндекс.Кассы результат проверки и отображаете пользователю нужную информацию.
Пользователь может прервать прохождение аутентификации, например если закроет страницу или всплывающее окно. Если после этого он захочет вернуться на страницу оплаты, заново создайте платеж, получите токен и инициализируйте виджет. Старый токен работать не будет — связанный с ним платеж останется в статусе
pending
(ожидает оплаты) до окончания действия токена, а после автоматически перейдет в статус
canceled
(отменен).
Если пользователь не прошел проверку (ввел неправильный код), платеж отменится и перейдет в статус
canceled
, в причинах отмены будет указано, что не пройдена аутентификация по 3-D Secure.
 Настройка прохождения аутентификации
Выберите способ прохождения аутентификации по 3-D Secure:
 Аутентификация на отдельной странице
Этот способ прохождения аутентификации используется в виджете по умолчанию.
Чтобы пользователь проходил аутентификацию по 3-D Secure на отдельной странице, при инициализации виджета передайте параметр
embedded_3ds
со значением
false
.
HTML
<!--Подключение библиотеки-->
<script src="https://kassa.yandex.ru/checkout-ui/v2.js"></script>

<!--HTML-элемент, в котором будет отображаться платежная форма-->
<div id="payment-form"></div>

<script>
//Инициализация виджета. Все параметры обязательные.
const checkout = new window.YandexCheckout({
    confirmation_token: 'confirmation-token', //Токен, который перед проведением оплаты нужно получить от Яндекс.Кассы
    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://kassa.yandex.ru/checkout-ui/v2.js"></script>

<!--HTML-элемент, в котором будет отображаться платежная форма-->
<div id="payment-form"></div>

<script>
//Инициализация виджета. Все параметры обязательные.
const checkout = new window.YandexCheckout({
    confirmation_token: 'confirmation-token', //Токен, который перед проведением оплаты нужно получить от Яндекс.Кассы
    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:
  1. Проверьте успешный сценарий.
  2. Проверьте неуспешный сценарий (пользователь не прошел проверку).
  3. Проверьте прерывание оплаты при прохождении аутентификации: уход со страницы эмитента или ее закрытие, закрытие всплывающего окна и страницы оплаты.
Вы можете проверить успешные и неуспешные сценарии с помощью тестовых банковских карт (карты работают только для вашего тестового магазина).
 Управление цветовой схемой интерфейса
По умолчанию в виджете белая платежная форма, а для важных элементов, например кнопки Заплатить, используется акцентный желтый цвет. Такой дизайн помогает пользователю сфокусироваться на главном — какой способ оплаты он выбрал, куда вводит данные и как перейти к оплате.
Виджет можно адаптировать под любой дизайн. Для настройки достаточно задать всего один или два цвета — остальные цвета виджет подберет сам. При необходимости вы можете откорректировать автоматически рассчитанные цвета, передав дополнительные параметры.
Примеры настройки цветовой схемы
 Настройка цветовой схемы
Цветовая схема задается при инициализации виджета с помощью объекта
colors
, переданного в объекте
customization
. В объекте
colors
задаются параметры, влияющие на цвета элементов интерфейса.
Можно задать максимум шесть параметров: два базовых и четыре дополнительных. Каждый из базовых параметров отвечает за определенную группу элементов интерфейса. Если передать такой параметр, виджет на его основе рассчитает все нужные цвета. При необходимости вы можете уточнить автоматически подобранные цвета с помощью дополнительных параметров.
Значения цветов необходимо задавать в шестнадцатеричном представлении (HEX), иначе виджет проигнорирует настройки.
Полезное для настройки цветовой схемы:
 Быстрый старт
Выберите, что вы хотите попробовать изменить: цвет кнопки Заплатить или цвет всей формы.
 Быстрый старт: кнопка Заплатить
Шаг 1. Добавьте в скрипт для инициализации виджета объект
customization
с объектом
colors
и параметром
controlPrimary
.
HTML
<!--Подключение библиотеки-->
<script src="https://kassa.yandex.ru/checkout-ui/v2.js"></script>

<!--HTML-элемент, в котором будет отображаться платежная форма-->
<div id="payment-form"></div>

<script>
//Инициализация виджета. Все параметры обязательные, кроме объекта customization.
const checkout = new window.YandexCheckout({
    confirmation_token: 'confirmation-token', //Токен, который перед проведением оплаты нужно получить от Яндекс.Кассы
    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://kassa.yandex.ru/checkout-ui/v2.js"></script>

<!--HTML-элемент, в котором будет отображаться платежная форма-->
<div id="payment-form"></div>

<script>
//Инициализация виджета. Все параметры обязательные, кроме объекта customization.
const checkout = new window.YandexCheckout({
    confirmation_token: 'confirmation-token', //Токен, который перед проведением оплаты нужно получить от Яндекс.Кассы
    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)
Готово! Виджет можно использовать для приема платежей от ваших пользователей.
 Варианты настройки: только платежная форма
Платежная форма состоит из блоков способов оплаты (кошелек в Яндекс.Деньгах, банковская карта, Сбербанк Онлайн), кнопок Apple Pay, Google Pay, кнопки Заплатить, сообщения о принятии оферты и логотипа Яндекс.Кассы.
Цвет фона, на котором располагаются элементы, — это цвет страницы оплаты или фона контейнера, в котором размещен виджет (вы изменяете его самостоятельно на странице оплаты). Кнопка Заплатить — акцентный элемент, который настраивается отдельно. На все остальные элементы влияют четыре параметра:
  • background
    (базовый цвет) — цвет фона блоков способов оплаты, цвет сообщений об ошибках и подсказок, внешний вид кнопок Apple Pay, Google Pay и логотипов.
  • text
     — цвет текста.
  • border
     — цвет границ и разделителей.
  • controlSecondary
     — цвет неакцентных элементов интерфейса.
Чтобы изменить цвет платежной формы, достаточно передать только
background
. В этом случае цвет границ, текста и неакцентных элементов виджет рассчитает автоматически.
Параметры, определяющие цвет формы
Рекомендуется для
background
выбирать цвет, близкий к цвету фона контейнера, в котором размещен виджет, для
text
 — контрастный цвет, который будет читаться на фоне платежной формы, на фоне неакцентных элементов и на фоне контейнера. Остальные цвета рекомендуется подбирать так, чтобы они хорошо смотрелись на фоне
background
.
Кнопки Apple Pay и Google Pay и логотипы Яндекс.Кассы и Яндекс.Денег могут быть только черными или белыми. Внешний вид зависит от параметра
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
 Справочник параметров и кодов ошибок
Описание параметров, которые передаются при инициализации виджета, и описание ошибок, связанных с инициализацией.
 Справочник параметров для инициализации виджета
Описание параметров, которые необходимо передать в экземпляр класса
YandexCheckout
на странице оплаты для инициализации виджета.
ПараметрТипОбязательностьОписание
confirmation_tokenstringОбязательныйТокен Яндекс.Кассы для инициализации виджета. Чтобы получить токен, нужно создать платеж
return_urlstringОбязательныйАдрес страницы, на которую пользователь вернется после завершения оплаты
3ds_embeddedbooleanНеобязательныйСпособ прохождения аутентификации по 3-D Secure:
true
 — во всплывающем окне,
false
 — на отдельной странице.
Значение по умолчанию:
false
customizationobjectНеобязательныйНастройка платежной формы. Сейчас доступна только настройка цветовой схемы
colorsobjectНеобязательныйПередается в 
customization
.
Настройка цветовой схемы. Перечень параметров, которые можно передать в colors
 Ошибки инициализации виджета
Если инициализация виджета закончилась неудачей, Яндекс.Касса передаст в callback-функцию код ошибки.
Код ошибкиОписание
token_required
Токен не передан. При инициализации виджета передайте
confirmation_token
invalid_token
Неверный токен. Для получения токена создайте платеж
token_expired
Истек срок действия токена. Для получения нового токена создайте платеж
return_url_required
URL возврата не передан. При инициализации виджета передайте
return_url
internal_service_error
При создании платежа возникла ошибка. Повторите инициализацию виджета
 Что почитать еще
Быстрый стартПроведение платежейВходящие уведомленияАвтоплатежи