Виджет ЮKassa — Прием платежей по API ЮKassa

Виджет ЮKassa

Виджет ЮKassa позволяет встроить на сайт готовую платежную форму. Пользователю будет доступно несколько способов оплаты: кошелек ЮMoney и привязанные к нему банковские карты, произвольная банковская карта, Apple Pay, Google Pay и Сбербанк Онлайн. С помощью виджета пользователь сможет сохранить в вашем магазине банковскую карту или кошелек ЮMoney для автоплатежей.

Платежная форма виджета ЮKassa

Платежная форма автоматически подстраивается под размеры устройства пользователя, проверяет вводимые данные и подсказывает пользователю, если что-то введено некорректно. Можно настроить язык интерфейса и цветовую схему платежной формы.

Чтобы принять платеж с помощью виджета, достаточно создать платеж по API ЮKassa, инициализировать виджет и отобразить форму на странице оплаты.

Для интеграции:

Ознакомьтесь со сценарием проведения платежа в виджете.
Настройте способы оплаты.
Подготовьте страницу оплаты.
Реализуйте проведение платежей.
При необходимости настройте способ прохождения аутентификации по 3-D Secure.
При необходимости реализуйте проведение автоплатежей.
При необходимости настройте цветовую схему виджета.
Настройте обработку ошибок инициализации виджета.

Сценарий проведения платежа

Пользователь переходит к оплате.
Вы отправляете ЮKassa запрос на создание платежа.
ЮKassa возвращает вам созданный объект платежа с токеном для инициализации виджета.
Вы инициализируете виджет и отображаете форму на странице оплаты.
Пользователь выбирает способ оплаты, вводит данные.
При необходимости виджет перенаправляет пользователя на страницу подтверждения платежа (например, для аутентификации по 3-D Secure).
Пользователь подтверждает платеж.
Виджет перенаправляет пользователя на страницу завершения оплаты на вашей стороне.
Вы отображаете нужную информацию, в зависимости от статуса платежа.

Готово!

Настройка способов оплаты

Виджет поддерживает следующие способы оплаты:

кошелек ЮMoney и привязанные к нему карты,
произвольная банковская карта,
Apple Pay,
Google Pay,
Сбербанк Онлайн.

Общие настройки

По умолчанию доступна оплата кошельком ЮMoney и с привязанных карт. Уточните у менеджера ЮKassa, какие еще способы оплаты вам разрешены.

Чтобы в виджете работала оплата с помощью Apple Pay и Google Pay, ваш сайт должен использовать HTTPS и действующий TLS/SSL-сертификат (минимальная версия — TLS v1.2). Для подключения Apple Pay выполните дополнительные настройки.

Подключение Apple Pay

Подключая Apple Pay в виджете, вы соглашаетесь с условиями использования платежного сервиса Apple Pay.

Шаг 1. Сообщите вашему менеджеру ЮKassa адрес сайта, на котором будет размещаться виджет.

Шаг 2. Скачайте файл merchant.ru.yoomoney и разместите его на своем сайте по адресу:

https://<домен вашего сайта>/.well-known/apple-developer-merchantid-domain-association

Путь к файлу должен быть строго таким — с точкой и дефисами. Точка в названии означает, что это скрытая папка.

Шаг 3. Чтобы оплата с помощью Apple Pay всегда была доступна в виджете, обновляйте TLS/SSL-сертификат не позднее, чем за 8 дней до окончания его срока действия.

Подготовка страницы оплаты

Для приема платежей подготовьте страницу оплаты: подключите библиотеку и разместите виджет.

Шаг 1. Подключите скрипт. Библиотека будет доступна в глобальной области видимости под именем

YooMoneyCheckoutWidget

Шаг 2. На страницу оплаты добавьте HTML-элемент, в котором хотите разместить форму. Задайте для данного элемента атрибут

Шаг 3. Для инициализации виджета создайте новый экземпляр класса

YooMoneyCheckoutWidget

и передайте в него

confirmation_token

, который нужно получить в ЮKassa перед проведением платежа,

return_url

, на который пользователь вернется после оплаты, и callback-функцию, которая будет принимать код ошибки. При необходимости настройте цветовую схему.

confirmation_token

нужно получать в ЮKassa для каждого платежа.

Шаг 4. Чтобы отобразить платежную форму, вызовите метод

render

. Передайте в него значение атрибута

, в котором нужно разместить форму, и при необходимости код, который нужно выполнить после отображения платежной формы.

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://merchant.site', //Ссылка на страницу завершения оплаты
    error_callback(error) {
        //Обработка ошибок инициализации
    }
});

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

В процессе оплаты виджет может отображать пользователю различные сообщения. Чтобы пользователь мог их прочитать, добавьте на ваш сайт поддержку кодировки UTF-8.

Перезагрузка виджета

Если на вашей странице оплаты пользователь может изменить заказ, вы можете перезагрузить инициализированный виджет без обновления всей страницы.

Как это выглядит:

Пользователь переходит к оплате.
Вы отправляете ЮKassa запрос на создание платежа, получаете токен, инициализируете виджет и отображаете форму на странице оплаты.
Пользователь что-то меняет в заказе.
Вы удаляете инициализированный виджет, вызвав метод
destroy
.
Вы отправляете ЮKassa запрос на создание платежа, получаете новый токен.
Вы инициализируете виджет с новым токеном и отображаете форму на странице оплаты.
Пользователь выбирает способ оплаты, вводит данные, подтверждает платеж.
Виджет перенаправляет пользователя на страницу завершения оплаты на вашей стороне.
Вы отображаете нужную информацию, в зависимости от статуса платежа.

Пример использования метода 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://merchant.site', //Ссылка на страницу завершения оплаты
    error_callback(error) {
        //Обработка ошибок инициализации
    }
});

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

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

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

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

Проведение платежа

Чтобы провести платеж:

Создайте платеж в ЮKassa
Инициализируйте виджет
Завершите оплату

Если хотите протестировать виджет, создайте платеж для вашего тестового магазина и заплатите одной из тестовых карт. Подробнее о тестировании платежей

Шаг 1. Создайте платеж

Для создания платежа отправьте ЮKassa запрос, передайте в нём данные для аутентификации запроса, ключ идемпотентности, объект

amount

с суммой платежа, объект

confirmation

с типом

embedded

и, при необходимости, параметр

description

с описанием транзакции, которое пользователь увидит при оплате. Также передайте параметр

capture

со значением

true

. Это значит, что вы получите деньги сразу после оплаты (при значении

false

нужная сумма заблокируется на счете пользователя, и после этого вы можете ее списать в удобное вам время).

По умолчанию тексты в платежной форме отображаются на русском. Чтобы изменить язык интерфейса на английский или немецкий, передайте в

confirmation

параметр

locale

со значением

en_US

или

de_DE

соответственно.

В запросе можно передать любые другие параметры, кроме

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 час. Если пользователь не оплатит в течение часа, виджет не инициализируется, токен нужно будет запрашивать заново. Если пользователь оплатит и вернется к форме, она отобразится с ошибкой.

Чтобы заново запросить токен, создайте платеж еще раз и инициализируйте виджет с новым токеном.

Шаг 3. Завершите оплату

Когда пользователь введет данные для оплаты и подтвердит платеж, ЮKassa перенаправит его на

return_url

, который вы передадите при инициализации виджета. Вам нужно самостоятельно узнать, как завершился платеж — успехом или неудачей — и отобразить пользователю нужную информацию.

Чтобы узнать статус платежа, подождите, когда придет уведомление от ЮKassa, или периодически отправляйте запросы, чтобы получить информацию о платеже .

Сохранение способа оплаты для автоплатежей

С помощью виджета ЮKassa вы можете сохранять способ оплаты, чтобы использовать его для автоплатежей, например, для ежемесячной оплаты подписки.

По умолчанию автоплатежи работают только в тестовом магазине. Если хотите использовать их в вашем реальном магазине, напишите менеджеру ЮKassa.

Если вам разрешено использование автоплатежей, вы можете проводить платежи:

с сохранением способа оплаты,
без сохранения способа оплаты.

Платеж с сохранением способа оплаты

Сохранение способа оплаты позволяет привязать карту или кошелек ЮMoney к вашему магазину. С помощью виджета вы можете проводить платежи с безусловным или с условным сохранением способа.

Безусловное сохранение способа оплаты — сохранение способа происходит по умолчанию, пользователь не может на это повлиять. Как это выглядит:

Вы на сайте предупреждаете пользователя, что сохраните его платежные данные, и рассказываете, как будете их использовать, например, с какой регулярностью вы будете списывать деньги и на какую сумму, как пользователь может отказаться от повторных списаний в вашем магазине. Вы на своей стороне получаете от пользователя согласие на проведение автоплатежей.
Виджет отображает пользователю только два способа оплаты: произвольной банковской картой или из кошелька ЮMoney. Когда пользователь выберет способ оплаты, виджет ему сообщит, что способ оплаты будет привязан к вашему магазину. При успешной оплате данные карты или кошелька автоматически сохранятся в ЮKassa.

Пример использования: подписка на регулярные платежи.

Платеж с безусловным сохранением способа оплаты

Условное сохранение способа оплаты — сохранение способа происходит по желанию пользователя. Как это выглядит:

Вы на сайте рассказываете о возможности сохранить платежные данные, о том, как вы будете их использовать и как потом от этого отказаться.
Виджет отображает пользователю все доступные способы оплаты. Если пользователь выберет произвольную карту или оплату из кошелька ЮMoney, виджет предложит ему сохранить данные для вашего магазина. Если пользователь согласится, при успешной оплате данные способа будут сохранены в ЮKassa, и вы сможете использовать идентификатор сохраненного способа оплаты для последующих платежей. Если не согласится, платеж пройдет без привязки данных к магазину.

Пример использования: привязка платежного средства к магазину для ускорения процесса оплаты при последующих платежах.

Платеж с условным сохранением способа оплаты

Платеж с безусловным сохранением способа оплаты

Шаг 1. Создайте платеж и передайте в нём

save_payment_method

со значением

true

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,
        "save_payment_method": true,
        "description": "Заказ №72"
      }'

Шаг 2. В ответе от ЮKassa получите

confirmation_token

— токен для инициализации виджета.

JSON
{
  "id": "25564507-000f-5000-9000-19878c91d156",
  "status": "pending",
  "paid": false,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "embedded",
    "confirmation_token": "ct-25564507-000f-5000-9000-19878c91d156"
  },
  "created_at": "2019-11-07T14:59:19.351Z",
  "description": "Заказ №72",
  "metadata": {},
  "recipient": {
    "account_id": "100001",
    "gateway_id": "1000001"
  },
  "refundable": false,
  "test": false
}

Шаг 3. Инициализируйте виджет.

Шаг 4. Далее проводите платеж как обычно.

Если оплата прошла успешно, получите идентификатор сохраненного способа оплаты.

Платеж с условным сохранением способа оплаты

Шаг 1. Создайте платеж, передавать

save_payment_method

не нужно.

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": "25564507-000f-5000-9000-19878c91d156",
  "status": "pending",
  "paid": false,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "embedded",
    "confirmation_token": "ct-2557c659-000f-5000-9000-12714806d854"
  },
  "created_at": "2019-11-07T14:59:19.351Z",
  "description": "Заказ №72",
  "metadata": {},
  "recipient": {
    "account_id": "100001",
    "gateway_id": "1000001"
  },
  "refundable": false,
  "test": false
}

Шаг 3. Инициализируйте виджет.

Шаг 4. Далее проводите платеж как обычно.

Если оплата прошла успешно, получите идентификатор сохраненного способа оплаты.

Получение идентификатора сохраненного способа оплаты

Шаг 1. Дождитесь, когда пользователь подтвердит оплату, и платеж перейдет в статус

succeeded

(или

waiting_for_capture

, если это платеж в две стадии). Чтобы узнать статус платежа, подождите, когда придет уведомление от ЮKassa, или периодически отправляйте запросы, чтобы получить информацию о платеже .

Шаг 2. Убедитесь, что способ оплаты сохранен: в объекте платежа значение

payment_method.saved

изменилось на

true

JSON
{
  "id": "25564507-000f-5000-9000-19878c91d156",
  "status": "succeeded",
  "paid": true,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "authorization_details": {
    "rrn": "10000000000",
    "auth_code": "000000"
  },
  "captured_at": "2018-07-18T17:20:50.825Z",
  "created_at": "2018-07-18T17:18:39.345Z",
  "description": "Заказ №72",
  "metadata": {},
  "payment_method": {
    "type": "bank_card",
    "id": "25564507-000f-5000-9000-19878c91d156",
    "saved": true,
    "card": {
      "first6": "555555",
      "last4": "4444",
      "expiry_month": "07",
      "expiry_year": "2022",
      "card_type": "MasterCard",
      "issuer_country": "RU",
      "issuer_name": "Sberbank"
    },
    "title": "Bank card *4444"
  },
  "refundable": true,
  "refunded_amount": {
    "value": "0.00",
    "currency": "RUB"
  },
  "recipient": {
    "account_id": "100001",
    "gateway_id": "1000001"
  },
  "test": false
}

Шаг 3. Сохраните идентификатор способа оплаты

payment_method.id

. Его нужно будет использовать в качестве идентификатора сохраненного способа оплаты при последующих платежах.

Готово!

Теперь вы можете проводить автоплатежи. Проведение платежа сохраненным способом оплаты нужно реализовать самостоятельно.

Платеж без сохранения способа оплаты

Вы можете проводить платежи без сохранения способа оплаты. Пользователь сможет оплатить любым доступным способом. Способ оплаты не сохранится.

Чтобы провести платеж без сохранения способа оплаты:

Шаг 1. Создайте платеж и передайте в нём

save_payment_method

со значением

false

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,
        "save_payment_method": false,
        "description": "Заказ №72"
      }'

Шаг 2. В ответе от ЮKassa получите

confirmation_token

— токен для инициализации виджета.

JSON
{
  "id": "25564507-000f-5000-9000-19878c91d156",
  "status": "pending",
  "paid": false,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "embedded",
    "confirmation_token": "ct-25564507-000f-5000-9000-19878c91d156"
  },
  "created_at": "2019-11-07T14:59:19.351Z",
  "description": "Заказ №72",
  "metadata": {},
  "recipient": {
    "account_id": "100001",
    "gateway_id": "1000001"
  },
  "refundable": false,
  "test": false
}

Шаг 3. Инициализируйте виджет.

Шаг 4. Далее проводите платеж как обычно.

Аутентификация по 3-D Secure при оплате картой

При оплате банковской картой пользователю обычно нужно подтвердить платеж — пройти аутентификацию по 3-D Secure. Для этого он вводит на странице эмитента специальный код из смс. Если всё хорошо, платеж проходит, если нет, платеж отменяется.

В виджете вы можете управлять тем, где пользователь будет проходить проверку — на отдельной странице или во всплывающем окне.

Аутентификация на отдельной странице (используется по умолчанию) — для прохождения аутентификации пользователь покидает ваш сайт: виджет перенаправляет его со страницы оплаты на страницу эмитента. После проверки эмитент перенаправляет пользователя на страницу завершения оплаты на вашей стороне.

Пример аутентификации на отдельной странице

Аутентификация во всплывающем окне — пользователь проходит аутентификацию, оставаясь на вашем сайте: виджет на странице оплаты отображает всплывающее окно со страницей эмитента. После проверки эмитент перенаправляет пользователя на страницу завершения оплаты на вашей стороне.

Пример аутентификации во всплывающем окне

Чтобы настроить прохождение аутентификации по 3-D Secure:

Ознакомьтесь с общим сценарием прохождения проверки.
Выберите способ прохождения аутентификации и настройте виджет.
Протестируйте выбранный способ.

Общий сценарий прохождения аутентификации

Аутентификация при оплате банковской картой проходит следующим образом:

Пользователь в платежной форме виджета вводит данные банковской карты и нажимает Заплатить.
Виджет перенаправляет пользователя на страницу эмитента или отображает всплывающее окно.
Пользователь проходит проверку.
Эмитент сообщает ЮKassa результат прохождения проверки.
Эмитент перенаправляет пользователя на страницу завершения оплаты —
return_url
, который вы указали при инициализации виджета.
Вы узнаёте у ЮKassa результат проверки и отображаете пользователю нужную информацию.

Пользователь может прервать прохождение аутентификации, например если закроет страницу или всплывающее окно. Если после этого он захочет вернуться на страницу оплаты, заново создайте платеж, получите токен и инициализируйте виджет. Старый токен работать не будет — связанный с ним платеж останется в статусе

pending

(ожидает оплаты) до окончания действия токена, а после автоматически перейдет в статус

canceled

(отменен).

Если пользователь не прошел проверку (ввел неправильный код), платеж отменится и перейдет в статус

canceled

, в причинах отмены будет указано, что не пройдена аутентификация по 3-D Secure.

Настройка прохождения аутентификации

Выберите способ прохождения аутентификации по 3-D Secure:

Отдельная страница
Всплывающее окно

Аутентификация на отдельной странице

Этот способ прохождения аутентификации используется в виджете по умолчанию.

Чтобы пользователь проходил аутентификацию по 3-D Secure на отдельной странице, при инициализации виджета передайте параметр

embedded_3ds

со значением

false

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://merchant.site', //Ссылка на страницу завершения оплаты
    embedded_3ds: false, // Способ прохождения аутентификации 3-D Secure — на отдельной странице.
    error_callback(error) {
        //Обработка ошибок инициализации
    }
});

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

Если параметр

embedded_3ds

не передать, то пользователь также будет проходить аутентификацию на отдельной странице.

Если пользователь в процессе аутентификации уйдет со страницы эмитента, например закроет ее или вернется на страницу оплаты, платеж прервется. Если пользователь захочет возобновить процесс оплаты, заново создайте платеж, инициализируйте виджет и отобразите платежную форму.

Аутентификация во всплывающем окне

Чтобы пользователь проходил аутентификацию по 3-D Secure во всплывающем окне, при инициализации виджета передайте параметр

embedded_3ds

со значением

true

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://merchant.site', //Ссылка на страницу завершения оплаты
    embedded_3ds: true, // Способ прохождения аутентификации 3-D Secure — во всплывающем окне
    error_callback(error) {
        //Обработка ошибок инициализации
    }
});

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

Размеры всплывающего окна:

максимальная ширина — 600 пикселей,
максимальная высота — 800 пикселей.

На мобильных устройствах всплывающее окно отображается на весь экран.

Если пользователь закроет всплывающее окно или уйдет со страницы оплаты, платеж прервется. При попытке закрыть всплывающее окно виджет предупредит пользователя, что оплата прервется и придется начинать заново. Если пользователь подтвердит действие, всплывающее окно закроется, на странице оплаты вместо платежной формы отобразится сообщение, что процесс прерван.

Сообщение на странице оплаты после закрытия всплывающего окна

Если пользователь захочет вернуться к оплате, заново создайте платеж, инициализируйте виджет и отобразите платежную форму.

Чтобы в браузере корректно отображались все сообщения, добавьте на ваш сайт поддержку кодировки UTF-8.

Тестирование прохождения аутентификации

Рекомендации по проверке прохождения аутентификации по 3-D Secure:

Проверьте успешный сценарий.
Проверьте неуспешный сценарий (пользователь не прошел проверку).
Проверьте прерывание оплаты при прохождении аутентификации: уход со страницы эмитента или ее закрытие, закрытие всплывающего окна и страницы оплаты.

Вы можете проверить успешные и неуспешные сценарии с помощью тестовых банковских карт (карты работают только для вашего тестового магазина).

Управление цветовой схемой интерфейса

По умолчанию в виджете белая платежная форма, а для важных элементов, например кнопки Заплатить, используется акцентный желтый цвет. Такой дизайн помогает пользователю сфокусироваться на главном — какой способ оплаты он выбрал, куда вводит данные и как перейти к оплате.

Виджет можно адаптировать под любой дизайн. Для настройки достаточно задать всего один или два цвета — остальные цвета виджет подберет сам. При необходимости вы можете откорректировать автоматически рассчитанные цвета, передав дополнительные параметры.

Примеры настройки цветовой схемы

Настройка цветовой схемы

Цветовая схема задается при инициализации виджета с помощью объекта

colors

, переданного в объекте

customization

. В объекте

colors

задаются параметры, влияющие на цвета элементов интерфейса.

Можно задать максимум шесть параметров: два базовых и четыре дополнительных. Каждый из базовых параметров отвечает за определенную группу элементов интерфейса. Если передать такой параметр, виджет на его основе рассчитает все нужные цвета. При необходимости вы можете уточнить автоматически подобранные цвета с помощью дополнительных параметров.

Значения цветов необходимо задавать в шестнадцатеричном представлении (HEX), иначе виджет проигнорирует настройки.

Полезное для настройки цветовой схемы:

Быстрый старт
Основные варианты настройки
Справочник параметров объекта colors

Быстрый старт

Выберите, что вы хотите попробовать изменить: цвет кнопки Заплатить или цвет всей формы.

Быстрый старт: кнопка Заплатить

Шаг 1. Добавьте в скрипт для инициализации виджета объект

customization

с объектом

colors

и параметром

controlPrimary

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: {
            //Цвет акцентных элементов: кнопка Заплатить, выбранные переключатели, опции и текстовые поля
            controlPrimary: '#00BF96' //Значение цвета в HEX
        }
    },
    error_callback(error) {
        //Обработка ошибок инициализации
    }
});

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

Шаг 2. Создайте платеж для тестового магазина и инициализируйте виджет.

Пример настроек из Быстрого старта (кнопка Заплатить)

Готово! Кнопка Заплатить и другие акцентные элементы изменили свой цвет.

Это самый простой способ изменить цвет акцентных элементов. Вы можете выбрать другой вариант настройки, если хотите уточнить автоматически рассчитанные цвета или изменить другие элементы интерфейса.

Быстрый старт: вся платежная форма

Шаг 1. Добавьте в скрипт для инициализации виджета объект

customization

с объектом

colors

и параметрами

controlPrimary

background

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: {
            //Цвет акцентных элементов: кнопка Заплатить, выбранные переключатели, опции и текстовые поля
            controlPrimary: '#00BF96', //Значение цвета в HEX

            //Цвет платежной формы и ее элементов
            background: '#F2F3F5' //Значение цвета в HEX
        }
    },
    error_callback(error) {
        //Обработка ошибок инициализации
    }
});

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

Шаг 2. Создайте платеж для тестового магазина и инициализируйте виджет.

Пример настроек из Быстрого старта (вся платежная форма)

Готово! Платежная форма и кнопка Заплатить изменили свои цвета.

Это самый простой способ изменить цвета всей платежной формы. Вы можете выбрать другой вариант настройки, если хотите уточнить автоматически рассчитанные цвета или изменить другие элементы интерфейса.

Варианты настройки цветовой схемы

Количество параметров, передаваемых в

colors

, зависит от того, что вы хотите изменить:

Только акцентные элементы: белая платежная форма подходит вашему сайту, а желтые акцентные элементы — нет.
Только платежная форма: желтые акценты устраивают, но белая форма не подходит (например, у вас на сайте есть темная тема).
Акцентные элементы и платежная форма: цвета по умолчанию не подходят совсем, нужно поменять цвета всех элементов.
Только детали: всё в целом устраивает, но нужно изменить какие-то детали, например цвет границ платежной формы.

Справочник всех параметров объекта colors

Варианты настройки: только акцентные элементы

Акцентные элементы в виджете — это то, что помогает сфокусироваться и призывает к действию: кнопка Заплатить, выбранные переключатели, опции, граница выбранного текстового поля.

На цвет акцентных элементов влияют два параметра:

controlPrimary
(базовый цвет) — цвет фона кнопки Заплатить и других акцентных элементов.
controlPrimaryContent
— цвет текста в кнопке и содержимого акцентных переключателей и опций (например, выставленный флажок).

Чтобы изменить цвет акцентных элементов, достаточно передать только

controlPrimary

. В этом случае виджет автоматически выберет в качестве цвета текста либо черный, либо белый цвет (наиболее контрастный к

controlPrimary

Параметры, определяющие цвет акцентных элементов — экран выбора способа оплаты

Параметры, определяющие цвет акцентных элементов — экран ввода данных

Рекомендуется для

controlPrimary

выбирать цвет, привлекающий внимание, для

controlPrimaryContent

— контрастный цвет, который будет читаться на фоне базового цвета.

Рекомендуется начать настройку с базового цвета, а дополнительный цвет использовать при необходимости:

Шаг 1. Добавьте в скрипт для инициализации виджета объект

customization

с объектом

colors

и параметром

controlPrimary

JavaScript
    customization: {
        //Настройка цветовой схемы, минимум один параметр, значения цветов в HEX
        colors: {
          controlPrimary: '#00BF96' // Базовый цвет кнопки Заплатить и других акцентных элементов
          // Цвет текста кнопки Заплатить, цвет флажка в переключателе подберется автоматически
        }
    },

Шаг 2. Создайте платеж для тестового магазина, инициализируйте виджет и проверьте, как смотрится платежная форма.

Шаг 3. При необходимости уточните автоматически рассчитанный цвет текста в кнопке Заплатить. Для этого добавьте в скрипт параметр

controlPrimaryContent

с нужным цветом и инициализируйте виджет заново (или обновите страницу оплаты).

JavaScript
    customization: {
        //Настройка цветовой схемы, минимум один параметр, значения цветов в HEX
        colors: {
          controlPrimary: '#00BF96', // Базовый цвет кнопки Заплатить и других акцентных элементов
          controlPrimaryContent: '#FFFFFF' // Цвет текста кнопки Заплатить, цвет флажка в переключателе
        }
    },

Пример настройки цветов акцентных элементов (controlPrimary и controlPrimaryContent)

Готово! Виджет можно использовать для приема платежей от ваших пользователей.

Вернуться к выбору варианта настройки

Варианты настройки: только платежная форма

Платежная форма состоит из блоков способов оплаты (кошелек ЮMoney, банковская карта, Сбербанк Онлайн), кнопок Apple Pay, Google Pay, сообщения о принятии оферты и логотипа ЮKassa.

Цвет фона, на котором располагаются элементы, — это цвет страницы оплаты или фона контейнера, в котором размещен виджет (вы изменяете его самостоятельно на странице оплаты). Кнопка Заплатить — акцентный элемент, который настраивается отдельно. На все остальные элементы влияют четыре параметра:

background
(базовый цвет) — цвет фона блоков способов оплаты, цвет сообщений об ошибках и подсказок, внешний вид кнопок Apple Pay, Google Pay и логотипов.
text
— цвет текста.
border
— цвет границ и разделителей.
controlSecondary
— цвет неакцентных элементов интерфейса.

Чтобы изменить цвет платежной формы, достаточно передать только

background

. В этом случае цвет границ, текста и неакцентных элементов виджет рассчитает автоматически.

Параметры, определяющие цвет формы — экран выбора способа оплаты

Параметры, определяющие цвет формы — экран ввода данных

Рекомендуется для

background

выбирать цвет, близкий к цвету фона контейнера, в котором размещен виджет, для

text

— контрастный цвет, который будет читаться на фоне платежной формы, на фоне неакцентных элементов и на фоне контейнера. Остальные цвета рекомендуется подбирать так, чтобы они хорошо смотрелись на фоне

background

Кнопки Apple Pay и Google Pay и логотип ЮKassa могут быть только черными или белыми. Внешний вид зависит от параметра

background

. Остальные параметры на них не влияют.

Рекомендуется начать настройку с базового цвета, а дополнительные цвета использовать при необходимости:

Шаг 1. Добавьте в скрипт для инициализации виджета объект

customization

с объектом

colors

и параметром

background

JavaScript
    customization: {
        //Настройка цветовой схемы, минимум один параметр, значения цветов в HEX
        colors: {
          background: '#F2F3F5' // Цвет фона платежной формы
          //Цвет текста, границ, неакцентных элементов рассчитается автоматически
        }
    },

Шаг 3. При необходимости уточните автоматически рассчитанные цвета текстов, границ или неакцентных элементов. Для этого добавьте в скрипт дополнительные параметры с нужными цветами и инициализируйте виджет заново (или обновите страницу оплаты).

JavaScript
    customization: {
        //Настройка цветовой схемы, минимум один параметр, значения цветов в HEX
        colors: {
          background: '#F2F3F5', // Цвет фона платежной формы
          text: '#222222', // Цвет текста
          border: '#D4D4D4', // Цвет границ и разделителей
          controlSecondary: '#AFBDCA' // Цвет неакцентных элементов интерфейса
        }
    },

Пример настройки цветов платежной формы (background, text, border, controlSecondary)

Готово! Виджет можно использовать для приема платежей от ваших пользователей.

Вернуться к выбору варианта настройки

Варианты настройки: акцентные элементы и платежная форма

Если вы хотите поменять все цвета виджета, используйте одновременно параметры для изменения акцентных элементов и платежной формы.

Рекомендуется начать настройку с базовых цветов, а дополнительные цвета использовать при необходимости:

Шаг 1. Добавьте в скрипт для инициализации виджета объект

customization

с объектом

colors

и параметрами

controlPrimary

background

JavaScript
    customization: {
        //Настройка цветовой схемы, минимум один параметр, значения цветов в HEX
        colors: {
          background: '#0D182F',  // Цвет фона платежной формы
          controlPrimary: '#00BF96' // Цвет кнопки Заплатить и других акцентных элементов
        }
    },

Шаг 3. При необходимости уточните автоматически рассчитанные цвета. Для этого добавьте в скрипт дополнительные параметры с нужными цветами и инициализируйте виджет заново (или обновите страницу оплаты).

JavaScript
    customization: {
        //Настройка цветовой схемы, минимум один параметр, значения цветов в HEX
        colors: {
          background: '#0D182F', // Цвет фона платежной формы
          controlPrimary: '#00BF96', // Цвет кнопки Заплатить и других акцентных элементов
          controlPrimaryContent: '#FFFFFF', // Цвет текста кнопки Заплатить
          controlSecondary: '#366093', // Цвет неакцентных элементов интерфейса
          border: '#244166', // Цвет границ и разделителей
          text: '#DBDCE0' // Цвет текста
        }
    },

Пример настройки всех цветов (все параметры). Фон контейнера задается отдельно

Готово! Виджет можно использовать для приема платежей от ваших пользователей.

Вернуться к выбору варианта настройки

Варианты настройки: только детали

Вы можете задать только дополнительные цвета, например только цвет границ. Если нужно изменить базовые цвета, используйте инструкции по настройке акцентных элементов и платежной формы.

Рекомендуемый порядок настройки:

Шаг 1. Добавьте в скрипт для инициализации виджета объект

customization

с объектом

colors

и нужными вам параметрами.

Готово! Виджет можно использовать для приема платежей от ваших пользователей.

Пример точечной настройки виджета

JavaScript
    customization: {
        //Настройка цветовой схемы, минимум один параметр, значения цветов в HEX
        colors: {
          controlPrimaryContent: '#0070F0', // Цвет текста кнопки Заплатить
          border: '#00BF96' // Цвет границ и разделителей
        }
    },

Пример точечной настройки виджета (controlPrimaryContent и border)

Вернуться к выбору варианта настройки

Справочник параметров для настройки цветовой схемы

Описание всех параметров объекте

colors

, которые можно использовать для настройки цветовой схемы.

Параметр	Описание	По умолчанию
controlPrimary	Цвет фона акцентных элементов: кнопка Заплатить, выбранные переключатели, опции, граница выбранного текстового поля. Рекомендуется использовать яркий цвет, привлекающий внимание	#FFCC00 (желтый)
controlPrimaryContent	Цвет текста в кнопке Заплатить и содержимого акцентных переключателей и опций (например, выставленный флажок). Рекомендуется использовать цвет, контрастный к controlPrimary . Если параметр не передан, цвет рассчитывается на основе controlPrimary	#000000 (черный) или #FFFFFF (белый) — выбирается контрастный к controlPrimary
background	Цвет фона платежной формы, цвет сообщений об ошибках и подсказок, а также внешний вид кнопок Apple Pay, Google Pay и логотипов. Рекомендуется использовать цвет, близкий к цвету фона контейнера, в котором размещен виджет	#FFFFFF (белый)
text	Цвет всех текстов на платежной форме, кроме текстов в кнопке Заплатить и во всплывающих подсказках. Если параметр не передан, цвет рассчитывается на основе background	Контрастный к background
border	Цвет границ и разделителей. Если параметр не передан, цвет рассчитывается на основе background	Контрастный к background
controlSecondary	Цвет неакцентных элементов интерфейса. Если параметр не передан, цвет рассчитывается на основе background	Контрастный к background

Справочник параметров и кодов ошибок

Описание параметров, которые передаются при инициализации виджета, и описание ошибок, связанных с инициализацией.

Справочник параметров для инициализации виджета

Описание параметров, которые необходимо передать в экземпляр класса

YooMoneyCheckoutWidget

на странице оплаты для инициализации виджета.

Параметр	Тип	Обязательность	Описание
confirmation_token	string	Обязательный	Токен ЮKassa для инициализации виджета. Чтобы получить токен, нужно создать платеж
return_url	string	Обязательный	Адрес страницы, на которую пользователь вернется после завершения оплаты. Адрес должен быть абсолютным (с указанием протокола и домена сайта). Пример: https://merchant-web-site.com/orderid-1111
3ds_embedded	boolean	Необязательный	Способ прохождения аутентификации по 3-D Secure: true — во всплывающем окне, false — на отдельной странице. Значение по умолчанию: false
customization	object	Необязательный	Настройка платежной формы. Сейчас доступна только настройка цветовой схемы
colors	object	Необязательный	Передается в customization . Настройка цветовой схемы. Перечень параметров, которые можно передать в colors

Ошибки инициализации виджета

Если инициализация виджета закончилась неудачей, ЮKassa передаст в callback-функцию код ошибки.

Код ошибки	Описание
internal_service_error	При создании платежа возникла ошибка. Повторите инициализацию виджета
invalid_return_url	Некорректный URL возврата. При инициализации виджета передайте в return_url абсолютный URL страницы завершения оплаты, указав в нем протокол и домен вашего сайта
invalid_token	Неверный токен. Для получения токена создайте платеж
return_url_required	URL возврата не передан. При инициализации виджета передайте return_url
token_expired	Истек срок действия токена. Для получения нового токена создайте платеж
token_required	Токен не передан. При инициализации виджета передайте confirmation_token

Что почитать еще

Быстрый старт Проведение платежей Входящие уведомления Автоплатежи

Сценарий проведения платежа

Настройка способов оплаты

Подготовка страницы оплаты

Проведение платежа

Сохранение способа оплаты для автоплатежей

Аутентификация по 3-D Secure при оплате картой

Управление цветовой схемой интерфейса

Справочник параметров и кодов ошибок