Типовые сценарии использования виджета Ю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://example.com', //Ссылка на страницу завершения оплаты

    //Настройка виджета (при необходимости)
    customization: {
        //Настройка цветовой схемы, минимум один параметр, значения цветов в HEX
        colors: {
            //Цвет акцентных элементов: кнопка Заплатить, выбранные переключатели, опции и текстовые поля
            controlPrimary: '#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": "ru_RU"
        },
        "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://example.com', //Ссылка на страницу завершения оплаты

    //Настройка виджета (при необходимости)
    customization: {
        //Настройка цветовой схемы, минимум один параметр, значения цветов в HEX
        colors: {
            //Цвет акцентных элементов: кнопка Заплатить, выбранные переключатели, опции и текстовые поля
            controlPrimary: '#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": "ru_RU"
        },
        "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"
      }'
 
После первого платежа
Получите идентификатор сохраненного способа оплаты.
 
Прием последующих платежей
Настройте проведение автоплатежа, когда пользователь выбирает заплатить в один клик.
 
Оплата банковской картой, Apple Pay и Google Pay
Расширение сценариев Товары с доставкой и Цифровые товары. Для тех, кто хочет использовать только форму оплаты банковской картой с возможностью платежа через Apple Pay и Google Pay.
 
Полезные материалы
 
Краткая памятка
 
Подготовка
Дополнительно для этого сценария: на странице оплаты в скрипте для инициализации виджета в 
payment_methods
передайте комбинацию нужных способов оплаты.
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://example.com', //Ссылка на страницу завершения оплаты

    //Настройка виджета
    customization: {
        //Выбор способа оплаты для отображения
        payment_methods: ['bank_card', 'apple_pay', 'google_pay'],
        //Настройка цветовой схемы (при необходимости), минимум один параметр, значения цветов в HEX
        colors: {
            //Цвет акцентных элементов: кнопка Заплатить, выбранные переключатели, опции и текстовые поля
            controlPrimary: '#00BF96' //Значение цвета в HEX
        }
    },
    error_callback: function(error) {
        //Обработка ошибок инициализации
    }
});

//Отображение платежной формы в контейнере
checkout.render('payment-form');
</script>
 
Прием платежа
Проводите платеж в соответствии с основным сценарием — Товары с доставкой или Цифровые товары.
 
Ваш экран выбора способа оплаты
Расширение сценариев Товары с доставкой и Цифровые товары. Для тех, кому не подходит готовый экран выбора способа оплаты в виджете или кто хочет добавить другие способы оплаты.
 
Полезные материалы
 
Краткая памятка
 
Подготовка
Дополнительно для этого сценария:
  • Реализуйте свой экран выбора способа оплаты.
  • Разместите на странице оплаты столько экземпляров виджета, сколько хотите отобразить способов оплаты. В скрипте для инициализации каждого виджета укажите в 
    payment_methods
    нужный способ оплаты (из тех, которые поддерживает виджет).
HTML
<!--Подключение библиотеки-->
<script src="https://yookassa.ru/checkout-widget/v1/checkout-widget.js"></script>

<!--Ваш код для отображения экрана выбора способа оплаты и HTML-элементы для отображения способов оплаты-->

<script>
//Инициализация виджета для первого способа оплаты
const checkout = new window.YooMoneyCheckoutWidget1({
    confirmation_token: 'confirmation-token', //Токен, который перед проведением оплаты нужно получить от ЮKassa
    return_url: 'https://example.com', //Ссылка на страницу завершения оплаты

    //Настройка виджета
    customization: {
        //Выбор способа оплаты для отображения
        payment_methods: ['bank_card']
    },
    error_callback: function(error) {
        //Обработка ошибок инициализации
    }
});

//Отображение платежной формы в контейнере
checkout.render('payment-form-1');
</script>

<script>
//Инициализация виджета для второго способа оплаты
const checkout = new window.YooMoneyCheckoutWidget2({
    confirmation_token: 'confirmation-token', //Токен, который перед проведением оплаты нужно получить от ЮKassa
    return_url: 'https://example.com', //Ссылка на страницу завершения оплаты

    //Настройка виджета
    customization: {
        //Выбор способа оплаты для отображения
        payment_methods: ['yoo_money']
    },
    error_callback: function(error) {
        //Обработка ошибок инициализации
    }
});

//Отображение платежной формы в контейнере
checkout.render('payment-form-2');
</script>
 
Прием платежа
Проводите платеж в соответствии с основным сценарием — Товары с доставкой или Цифровые товары. Все экземпляры виджета инициализируйте с помощью одного и того же токена. Токен будет работать, пока не закончится срок его жизни или пока пользователь не подтвердит платеж.
 
Что почитать еще
Сценарии интеграции ЮKassaCheckout.js