UI-библиотека — это готовая форма для приема платежей банковской картой. Работает в паре с Checkout.js.
Что умеет форма:
- показывать сообщения пользователям — по-русски и по-английски;
- валидировать данные карты «на лету»;
- узнавать банк, в котором выпущена карта, и перекрашивать изображение карты в его фирменные цвета.
Чтобы вам не пришлось обрабатывать платежные данные в своей системе, Checkout UI обменивает данные, которые ввел пользователь, на одноразовый платежный токен. Вам нужно отправить этот токен в запросе на создание платежа.
Библиотека подключается только через CDN.
Подключите скрипт из CDN. Библиотека будет доступна в глобальной области видимости под именем
YooMoneyCheckoutUI
.Подключение скрипта из CDN
HTML
<script src="https://static.yoomoney.ru/checkout-ui/v1/checkout-ui.js"></script>
После этого вы можете создать инстанс от YooMoneyCheckoutUI и использовать
$checkout
для генерации токена с данными банковской карты.Чтобы вы могли создавать платежи с использованием токена, запросите разрешение у вашего менеджера ЮKassa.
Создание инстанса от YooMoneyCheckoutUI
JavaScript
const $checkout = YooMoneyCheckoutUI(123456); //123456 — ваш идентификатор магазина
Вы можете настроить форму:
- выбрать язык интерфейса (для отображения надписей на форме и пользовательских ошибок);
- сумму, которую будете показывать на форме;
- указать, что нужно показать сообщение об автоплатежах (для случаев, когда после успешной оплаты включится возможность проводить безакцептные списания с этой карты в вашем сервисе).
Пример настройки формы
JavaScript
const $checkout = YooMoneyCheckoutUI(123456, { language: 'en', domSelector: '.my-selector', amount: 99.99 });
Параметр | Описание | Тип | По умолчанию |
---|---|---|---|
language | Язык интерфейса (надписи на форме, ответы, ошибки). Возможные значения: en или ru | string | ru |
amount | Сумма оплаты, которая отображается на форме | number | 0 |
isRecurrent | Отрисовать на форме сообщение о том, что будут производиться безакцептные списания (рекурренты) | boolean | false |
JSON
{ // язык вывода ответов language: string ('en' | 'ru') ['ru'], // стоимость, которую нужно показать на форме amount: number ['0'], // Будут производиться реруррентные платежи isRecurrent: true [false] }
Метод | Описание | Принимает | Возвращает |
---|---|---|---|
.open | Показывает форму | {void} | |
.close | Скрывает форму | {void} | |
.on | Включает подписку на события | yc_error , yc_success | {void} |
.showLantern | Выводит сообщение для пользователя | text string | {void} |
.hideLantern | Скрывает сообщение для пользователя | {void} | |
.toggleLantern | Переключает состояние сообщения для пользователя | text string | {void} |
.chargeSuccessful | Сообщает форме об успешном ответе от API ЮKassa | text string | {void} |
.chargeFailful | Сообщает форме об ошибке от API ЮKassa | text string | {void} |
Показывает платежную форму.
JavaScript
const $checkout = YooMoneyCheckoutUI(123456); $checkout.open();
Скрывает платежную форму.
JavaScript
const $checkout = YooMoneyCheckoutUI (123456); $checkout.close ();
Позволяет подписаться на события, возникающие при работе с библиотекой.
Доступные подписки:
- на ошибки — yc_error;
- на успешное создание токена — yc_success.
Событие | Описание | Возвращает |
---|---|---|
yc_error | Произошла ошибка любого рода | Объект точно такого же вида, что и ошибка в YooMoney JS |
yc_success | Токен успешно создан | Объект точно такого же вида, что и успешный ответ в YooMoney JS |
Пример с ошибкой
JavaScript
$checkout.on('yc_error', response => { /* { status: 'error', error: { type: 'validation_error', message: undefined, status_code: 400, code: undefined, params: [ { code: 'invalid_number', message: 'Неверный номер карты' }, { code: 'invalid_expiry_month', message: 'Невалидное значение месяца' } ] } } */ });
Пример успешного создания токена
JavaScript
$checkout.on('yc_success', response => { /* { status: 'success', data: { message: 'Токен для оплаты создан', status_code: 200, type: 'payment_token_created', response: { paymentToken: 'eyJlbmNyeXB0ZWRNZXNzYWdlIjoiWlc1amNubHdkR1ZrVFdWemMyRm5aUT09IiwiZXBoZW1lcmFsUHVibGljS2V5IjoiWlhCb1pXMWxjbUZzVUhWaWJHbGpTMlY1IiwidGFnIjoiYzJsbmJtRjBkWEpsIn0K' } } } */ console.log(response); });
Показывает пользователю сообщение над формой (если произошла какая-нибудь ошибка при запросах по API ЮKassa).
Параметр | Тип | Описание |
---|---|---|
text | string | Текст ошибки |
JavaScript
const $checkout = YooMoneyCheckoutUI(123456); $checkout.showLantern('Текст ошибки');
Позволяет скрыть сообщение с ошибкой.
JavaScript
const $checkout = YooMoneyCheckoutUI(123456); $checkout.hideLantern();
Открывает или скрывает сообщение с ошибкой.
Параметр | Тип | Описание |
---|---|---|
text | string | Текст ошибки |
JavaScript
const $checkout = YooMoneyCheckoutUI(123456); $checkout.toggleLantern('Текст ошибки');
Сообщает форме об успешном ответе от API ЮKassa.
После вызова этого метода:
- сначала будет скрыто сообщение об ошибке (если оно открыто);
- потом закроется форма.
JavaScript
const $checkout = YooMoneyCheckoutUI(123456); // Открываем форму $checkout.open(); // Токен успешно создан $checkout.on('yc_success', () => { // Запрос к API ЮKassa // ... // Если оплата прошла успешно, то вызываем метод $checkout.chargeSuccessful(); });
Сообщает платежной форме о том, что от API ЮKassa пришла ошибка.
После вызова этого метода пользователю показывается сообщение с ошибкой.
Параметр | Тип | Описание |
---|---|---|
text | string | Текст ошибки |
JavaScript
const $checkout = YooMoneyCheckoutUI(123456); // Открываем форму $checkout.open(); // Токен успешно создан $checkout.on('yc_success', () => { // Запрос к API ЮKassa // ... // Оплата не прошла $checkout.chargeFailful(); });