Инструкции
Помощь
Подключить ЮKassa
Типовые сценарии использования виджета ЮKassa
В этой статье приведено несколько типовых сценариев интеграции с использованием виджета ЮKassa.
Основные сценарии:
Расширения основных сценариев:
Товары с доставкой
Кому подойдет этот сценарий:
  • вы продаете физические товары с доставкой и хотите списывать оплату с пользователя только после проверки, что нужные товары есть на складе;
  • вы оказываете услуги и хотите списывать оплату с пользователя только после предварительного обсуждения или проверки заказа.
Полезные материалы
Краткая памятка
Подготовка
Шаг 1. Подготовьтесь к интеграции: получите данные для аутентификации запросов, подключите нужные способы оплаты и подготовьте свой сайт.
Шаг 2. Подготовьте страницу оплаты: разместите виджет, настройте отображение платежной формы и при необходимости настройте цветовую схему виджета.
HTML

<script src="https://yookassa.ru/checkout-widget/v1/checkout-widget.js"></script>


<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>


<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