Подробная инструкция по использованию виджета ЮKassa для приема платежей. Если уже проинтегрировались с помощью Быстрого старта для виджета и вас всё устраивает, можете пропустить эту статью.
Подключите нужные вам способы оплаты, настройте свой сайт и подготовьте страницу оплаты.
Виджет поддерживает несколько способов оплаты. На платежной форме будут отображаться те способы, которые подключены в вашем магазине. Способы оплаты можно проверить и подключить в личном кабинете, в разделе Настройки — Способы оплаты, или через вашего менеджера ЮKassa.
Некоторые способы оплаты отображаются на платежной форме виджета только при определенных условиях.
Способ оплаты | Подключение |
---|---|
ЮMoney | Доступно по умолчанию |
Банковская карта | Доступно, если магазину разрешено принимать платежи этим способом |
Mir Pay | Доступно, если магазину разрешено принимать платежи этим способом. Кнопка отображается при оплате с мобильных устройств на Android. |
SberPay | Доступно, если магазину разрешено принимать платежи этим способом. |
СБП (Система быстрых платежей) | Доступно, если магазину разрешено принимать платежи этим способом. |
В процессе оплаты виджет может отображать пользователю различные сообщения.
Чтобы пользователь мог их прочитать, сайт должен работать в кодировке UTF-8.
Чтобы проверить соответствие вашего сайта этим требованиям, обратитесь к вашему хостинг-провайдеру или протестируйте сайт самостоятельно с помощью сервисов для проверки TLS, SSL и уязвимостей.
Страница оплаты — это та страница, на которой пользователь увидит платежную форму, введет данные и подтвердит платеж. На этой странице нужно разместить виджет и отобразить платежную форму.
Шаг 1. Подключите скрипт. Библиотека будет доступна в глобальной области видимости под именем
YooMoneyCheckoutWidget
.Шаг 2. На страницу оплаты добавьте HTML-элемент, в котором хотите разместить форму. Задайте для данного элемента атрибут
id
. Минимальная ширина контейнера для отображения платежной формы — 288 пикселей.Шаг 3. Для инициализации виджета создайте новый экземпляр класса
YooMoneyCheckoutWidget
и передайте в него следующие параметры:confirmation_token
, который нужно получить в ЮKassa перед проведением платежа.- callback-функцию, которая будет принимать код ошибки.
Передайте
return_url
, если вы хотите, чтобы пользователь после платежа перешел на страницу завершения оплаты. Если вы хотите по-своему взаимодействовать с пользователем, настройте обработку событий процесса оплаты.При необходимости вы можете настроить цветовую схему платежной формы и отображение способов оплаты.
Шаг 4. Чтобы отобразить платежную форму, вызовите метод
render
. Передайте в него значение атрибута id
, в котором нужно разместить форму, и при необходимости код, который нужно выполнить после отображения платежной формы.<script src="https://yookassa.ru/checkout-widget/v1/checkout-widget.js"></script> <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>
Если на вашей странице оплаты пользователь может изменить заказ, вы можете перезагрузить инициализированный виджет без обновления всей страницы.
Как это выглядит:
- Пользователь переходит к оплате.
- Вы отправляете ЮKassa запрос на создание платежа, получаете токен, инициализируете виджет и отображаете форму на странице оплаты.
- Пользователь что-то меняет в заказе.
- Вы удаляете инициализированный виджет, вызвав метод
destroy
. - Вы отправляете ЮKassa запрос на создание платежа, получаете новый токен.
- Вы инициализируете виджет с новым токеном и отображаете форму на странице оплаты.
- Пользователь выбирает способ оплаты, вводит данные, подтверждает платеж.
- Виджет перенаправляет пользователя на вашу страницу завершения оплаты.
- Вы отображаете нужную информацию, в зависимости от статуса платежа.
Пример использования метода destroy
<script src="https://yookassa.ru/checkout-widget/v1/checkout-widget.js"></script> <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>
Чтобы провести платеж:
Для создания платежа отправьте ЮKassa запрос, передайте в нём данные для аутентификации запроса, ключ идемпотентности, объект
amount
с суммой платежа, объект confirmation
с типом embedded
и, при необходимости, параметр description
с описанием транзакции, которое вы увидите в личном кабинете и при запросе информации о платеже .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" }'
В объекте платежа ЮKassa вернет
confirmation_token
.{ "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": "100500", "gateway_id": "100700" }, "refundable": false, "test": false }
Используйте этот токен для создания экземпляра класса
YooMoneyCheckoutWidget
и инициализации виджета.Токен одноразовый, срок действия — 1 час. Если использовать токен с истекшим сроком действия, вернется ошибка
token_expired
, виджет не инициализируется. Если пользователь оплатит и вернется к той же форме, она отобразится с ошибкой. Если пользователь не успеет подтвердить оплату в течение срока действия токена, ЮKassa отменит платеж, вам нужно будет завершить оплату (см. шаг 3).Чтобы заново запросить токен, создайте платеж еще раз и инициализируйте виджет с новым токеном.
Когда пользователь введет данные и подтвердит платеж или когда закончится срок действия токена, ЮKassa перенаправит пользователя на
return_url
, который вы передадите при инициализации виджета или выполнит действия, настроенные вами для события завершения оплаты. Вам нужно самостоятельно узнать, как завершился платеж — успехом или неудачей — и отобразить пользователю нужную информацию.Чтобы узнать статус платежа, подождите, когда придет уведомление от ЮKassa, или периодически отправляйте запросы, чтобы получить информацию о платеже .
Готово!
Типовые сценарии интеграции виджетаПроведение платежейВходящие уведомленияСправочник виджета