Типовые сценарии использования виджета ЮKassa
В этой статье приведено несколько типовых сценариев интеграции с использованием виджета ЮKassa.
Основные сценарии:
Расширения основных сценариев:
Товары с доставкой
Кому подойдет этот сценарий:
  • вы продаете физические товары с доставкой и хотите списывать оплату с пользователя только после проверки, что нужные товары есть на складе;
  • вы оказываете услуги и хотите списывать оплату с пользователя только после предварительного обсуждения или проверки заказа.
Полезные материалы
Краткая памятка
Подготовка
Шаг 1. Подготовьтесь к интеграции: получите данные для аутентификации запросов, подключите нужные способы оплаты и подготовьте свой сайт.
Шаг 2. Подготовьте страницу оплаты: разместите виджет, настройте отображение платежной формы и при необходимости настройте цветовую схему виджета.
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: {
            //Цвет акцентных элементов: кнопка Заплатить, выбранные переключатели, опции и текстовые поля
            control_primary: '#00BF96' //Значение цвета в HEX
        }
    },
    error_callback: function(error) {
        //Обработка ошибок инициализации
    }
});

//Отображение платежной формы в контейнере
checkout.render('payment-form');
</script>
Прием платежа
Шаг 1. Настройте создание платежа и получение токена для инициализации виджета, в запросе на создание платежа передайте дополнительно:
  • параметр
    capture
    со значением
    false
    , чтобы провести платеж в две стадии;
  • параметр
    confirmation.locale
    , если хотите настроить язык текста интерфейса платежной формы.
Пример запроса на создание платежа
cURL
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",
          "locale": "en_US"
        },
        "capture": false,
        "description": "Заказ №72"
      }'
Шаг 2. Настройте инициализацию виджета и обработку ошибок.
Шаг 3. Настройте завершение оплаты и отображение пользователю информации в зависимости от статуса платежа.
Шаг 4. Настройте списание оплаты и отмену платежа после успешного подтверждения платежа пользователем.
После платежа
При необходимости настройте возврат платежа.
Цифровые товары
Кому подойдет этот сценарий: вы продаете цифровые товары или услуги и предоставляете их пользователю сразу после оплаты.
Полезные материалы
Краткая памятка
Подготовка
Шаг 1. Подготовьтесь к интеграции: получите данные для аутентификации запросов, подключите нужные способы оплаты и подготовьте свой сайт.
Шаг 2. Подготовьте страницу оплаты: разместите виджет, настройте отображение платежной формы и при необходимости настройте цветовую схему виджета.
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: {
            //Цвет акцентных элементов: кнопка Заплатить, выбранные переключатели, опции и текстовые поля
            control_primary: '#00BF96' //Значение цвета в HEX
        }
    },
    error_callback: function(error) {
        //Обработка ошибок инициализации
    }
});

//Отображение платежной формы в контейнере
checkout.render('payment-form');
</script>
Прием платежа
Шаг 1. Настройте создание платежа и получение токена для инициализации виджета, в запросе на создание платежа передайте дополнительно:
  • параметр
    capture
    со значением
    true
    , чтобы списать деньги сразу после подтверждения платежа пользователем;
  • параметр
    confirmation.locale
    , если хотите настроить язык текста интерфейса платежной формы.
Пример запроса на создание платежа
cURL
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",
          "locale": "en_US"
        },
        "capture": false,
        "description": "Заказ №72"
      }'
Шаг 2. Настройте инициализацию виджета и обработку ошибок.
Шаг 3. Настройте завершение оплаты и отображение пользователю информации в зависимости от статуса платежа.
После платежа
При необходимости настройте возврат платежа.
Подписка на автоплатежи
Расширение сценариев Товары с доставкой и Цифровые товары. Для тех, кто хочет регулярно списывать абонентскую плату за подписку или реализовать другие повторные платежи.
Полезные материалы
Краткая памятка
Подготовка
Дополнительно для автоплатежей:
  • Сообщите менеджеру ЮKassa, что собираетесь проводить автоплатежи.
  • Реализуйте получение согласие пользователя на проведение автоплатежей.
Прием первого платежа
При создании платежа передайте в запросе параметр
save_payment_method
со значением
true
, чтобы провести платеж с сохранением способа оплаты. Остальные параметры передайте в зависимости от вашего сценария.
Пример запроса на создание платежа
cURL
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",
          "locale": "ru_RU"
        },
        "capture": true,
        "save_payment_method": true,
        "description": "Заказ №72"
      }'
После первого платежа
Получите идентификатор сохраненного способа оплаты.
Прием последующих платежей
Настройте проведение регулярных автоплатежей с использованием сохраненного способа оплаты.
Покупка в один клик
Расширение сценариев Товары с доставкой и Цифровые товары.
Кому подойдет этот сценарий:
  • вы хотите дать возможность пользователю оплачивать покупки моментально, в один клик;
  • вы собираетесь самостоятельно реализовать форму выбора способа оплаты.
Если вы хотите использовать готовую форму выбора способа оплаты и сохранять только банковскую карту, используйте покупку с выбором запомненной карты.
Полезные материалы
Краткая памятка
Подготовка
Дополнительно для автоплатежей:
  • Сообщите менеджеру ЮKassa, что собираетесь проводить автоплатежи.
  • Реализуйте получение согласие пользователя на проведение автоплатежей.
Прием первого платежа
При создании платежа не передавайте в запросе параметр
save_payment_method
. Остальные параметры передайте в зависимости от вашего сценария.
Пример запроса на создание платежа
cURL
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",
          "locale": "ru_RU"
        },
        "capture": true,
        "description": "Заказ №72"
      }'
После первого платежа
Получите идентификатор сохраненного способа оплаты.
Прием последующих платежей
Настройте проведение автоплатежа, когда пользователь выбирает заплатить в один клик.
Покупка с выбором запомненной карты
Расширение сценариев Товары с доставкой и Цифровые товары.
Кому подойдет этот сценарий:
  • вы хотите запомнить банковскую карту пользователя и отображать ее при повторной оплате;
  • вы собираетесь использовать готовую форму выбора способа оплаты.
Если вы хотите самостоятельно реализовать форму выбора способа оплаты и сохранить кошелек ЮMoney или банковскую карту, используйте покупку в один клик.
Полезные материалы
Краткая памятка
Подготовка
Прием первого платежа
При создании платежа передайте
merchant_customer_id
с идентификатором пользователя в вашей системе. Остальные параметры передайте в зависимости от вашего сценария.
Пример запроса на создание платежа
cURL
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",
        "merchant_customer_id": "+79999999999"
      }'
Прием последующих платежей
В запросе на создание платежа передавайте идентификатор пользователя в вашей системе

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

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