Интеграция виджета
Подробная инструкция по использованию виджета ЮKassa для приема платежей. Если уже проинтегрировались с помощью Быстрого старта для виджета и вас всё устраивает, можете пропустить эту статью.
 
Предварительная настройка
Подключите нужные вам способы оплаты, настройте свой сайт и подготовьте страницу оплаты.
 
Подключение способов оплаты
Виджет поддерживает несколько способов оплаты. На платежной форме будут отображаться те способы, которые подключены в вашем магазине. Способы оплаты можно проверить и подключить в личном кабинете, в разделе Настройки — Способы оплаты, или через вашего менеджера ЮKassa.
Некоторые способы оплаты отображаются на платежной форме виджета только при определенных условиях.
Способ оплатыПодключение
ЮMoneyДоступно по умолчанию
Банковская картаДоступно, если магазину разрешено принимать платежи этим способом
Apple Pay
Доступно, если магазину разрешено принимать платежи этим способом. Дополнительно нужно подготовить сайт и прописать настройки в личном кабинете.
Кнопка отображается на платежной форме, если:
  • браузер пользователя — Safari версии 11.1 и новее;
  • пользователь вошел в свой аккаунт на Apple.
Подключая Apple Pay в виджете, вы соглашаетесь с условиями использования платежного сервиса Apple Pay
Google PayДоступно, если магазину разрешено принимать платежи этим способом. Дополнительно нужно подготовить сайт
СберБанк Онлайн или SberPayДоступно, если магазину разрешено принимать платежи этим способом. Доступен либо SberPay, либо СберБанк Онлайн. Подробнее об оплате через СберБанк
 
Подготовка сайта
В процессе оплаты виджет может отображать пользователю различные сообщения. Чтобы пользователь мог их прочитать, добавьте на ваш сайт поддержку кодировки UTF-8.
Чтобы в виджете работала оплата с помощью Apple Pay и Google Pay, ваш сайт должен использовать HTTPS и действующий TLS-сертификат (минимальная версия — TLS v1.2). Чтобы оплата с помощью Apple Pay всегда была доступна в виджете, обновляйте TLS-сертификат не позднее, чем за 8 дней до окончания его срока действия.
Чтобы проверить соответствие вашего сайта этим требованиям, обратитесь к вашему хостинг-провайдеру или протестируйте сайт самостоятельно с помощью сервисов для проверки TLS, SSL и уязвимостей.
 
Подготовка страницы оплаты
Страница оплаты — это та страница, на которой пользователь увидит платежную форму, введет данные и подтвердит платеж. На этой странице нужно разместить виджет и отобразить платежную форму.
Вы можете настроить отображение виджета во всплывающем окне. При таком способе отображения вам не нужно реализовывать страницу оплаты и встраивать в нее виджет.
 
Размещение виджета и отображение платежной формы
Шаг 1. Подключите скрипт. Библиотека будет доступна в глобальной области видимости под именем
YooMoneyCheckoutWidget
.
Шаг 2. На страницу оплаты добавьте HTML-элемент, в котором хотите разместить форму. Задайте для данного элемента атрибут
id
. Минимальная ширина контейнера для отображения платежной формы — 280 пикселей.
Шаг 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://example.com', //Ссылка на страницу завершения оплаты
    error_callback: function(error) {
        //Обработка ошибок инициализации
    }
});

//Отображение платежной формы в контейнере
checkout.render('payment-form')
//Метод возвращает Promise, исполнение которого говорит о полной загрузке платежной формы (можно не использовать).
  .then(() => {
     //Код, который нужно выполнить после отображения платежной формы.
  });
</script>
 
Перезагрузка виджета
Если на вашей странице оплаты пользователь может изменить заказ, вы можете перезагрузить инициализированный виджет без обновления всей страницы.
Как это выглядит:
  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://example.com', //Ссылка на страницу завершения оплаты
    error_callback: function(error) {
        //Обработка ошибок инициализации
    }
});

//Отображение платежной формы в контейнере
checkout.render('payment-form')
//Метод возвращает Promise, исполнение которого говорит о полной загрузке платежной формы (можно не использовать).
  .then(() => {
     //Код, который нужно выполнить после отображения платежной формы.
  });

//Удаление платежной формы из контейнера
checkout.destroy();

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

//Отображение платежной формы в контейнере
checkoutNew.render('payment-form')
//Метод возвращает Promise, исполнение которого говорит о полной загрузке платежной формы (можно не использовать).
    .then(() => {
       //Код, который нужно выполнить после отображения платежной формы.
  });
</script>
 
Проведение платежа
Чтобы провести платеж:
  1. Создайте платеж в ЮKassa
  2. Инициализируйте виджет и отобразите форму
  3. Завершите оплату
Если при оплате банковской картой, через Apple Pay и Google Pay вы хотите самостоятельно принимать решение, что сообщать пользователю при неуспешном платеже, напишите менеджеру ЮKassa.
 
Шаг 1. Создайте платеж
Для создания платежа отправьте ЮKassa запрос, передайте в нём данные для аутентификации запроса, ключ идемпотентности, объект
amount
с суммой платежа, объект
confirmation
с типом
embedded
и, при необходимости, параметр
description
с описанием транзакции, которое вы увидите в личном кабинете и при запросе информации о платеже .
В запросе можно передать любые другие параметры, кроме
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 час. Если использовать токен с истекшим сроком действия, вернется ошибка
token_expired
, виджет не инициализируется. Если пользователь оплатит и вернется к той же форме, она отобразится с ошибкой. Если пользователь не успеет подтвердить оплату в течение срока действия токена, ЮKassa отменит платеж, вам нужно будет завершить оплату (см. шаг 3).
Чтобы заново запросить токен, создайте платеж еще раз и инициализируйте виджет с новым токеном.
 
Шаг 3. Завершите оплату
Когда пользователь введет данные и подтвердит платеж или когда закончится срок действия токена, ЮKassa перенаправит пользователя на 
return_url
, который вы передадите при инициализации виджета. Вам нужно самостоятельно узнать, как завершился платеж — успехом или неудачей — и отобразить пользователю нужную информацию.
Чтобы узнать статус платежа, подождите, когда придет уведомление от ЮKassa, или периодически отправляйте запросы, чтобы получить информацию о платеже .
Готово!

Есть вопросы или замечания по документации?

Можем созвониться и обсудить их лично: мы поможем вам разобраться, а вы нам — понять, что тут нужно улучшить. Для этого оставьте свои контакты и выберите время.
Да, хочу обсудить
 
Что почитать еще
Типовые сценарии интеграции виджетаПроведение платежейВходящие уведомленияСправочник виджета