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

YandexCheckout UI

UI-библиотека — это готовая форма для приема платежей банковской картой. Работает в паре с YandexCheckout.js.

Что умеет форма:

показывать сообщения пользователям — по-русски и по-английски;
валидировать данные карты «на лету»;
узнавать банк, в котором выпущена карта, и перекрашивать изображение карты в его фирменные цвета.

Чтобы вам не пришлось обрабатывать платежные данные в своей системе, YandexCheckout UI обменивает данные, которые ввел пользователь, на одноразовый платежный токен. Вам нужно отправить этот токен в запросе на создание платежа.

Инициализация

Библиотека подключается только через CDN.

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

YandexCheckoutUI

Подключение скрипта из CDN

HTML
<script src="https://static.yamoney.ru/checkout-ui/v1/checkout-ui.js"></script>

После этого вы можете создать инстанс от YandexCheckoutUI и использовать

$checkout

для генерации токена с данными банковской карты.

Чтобы вы могли создавать платежи с использованием токена, запросите разрешение у вашего менеджера ЮKassa.

Создание инстанса от YandexCheckoutUI

JavaScript
const $checkout = YandexCheckoutUI(123456);

//123456 — ваш идентификатор магазина

Конфигурация

Вы можете настроить форму:

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

Пример настройки формы

JavaScript
const $checkout = YandexCheckoutUI(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}

.open

Показывает платежную форму.

JavaScript
const $checkout = YandexCheckoutUI(123456);
$checkout.open();

.close

Скрывает платежную форму.

JavaScript
const $checkout = YandexCheckoutUI (123456);
$checkout.close ();

.on

Позволяет подписаться на события, возникающие при работе с библиотекой.

Доступные подписки:

на ошибки —
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);
});

.showLantern

Показывает пользователю сообщение над формой (если произошла какая-нибудь ошибка при запросах по API ЮKassa).

Параметр	Тип	Описание
text	string	Текст ошибки

JavaScript
const $checkout = YandexCheckoutUI(123456);
$checkout.showLantern('Текст ошибки');

.hideLantern

Позволяет скрыть сообщение с ошибкой.

JavaScript
const $checkout = YandexCheckout(123456);
$checkout.hideLantern();

.toggleLantern

Открывает или скрывает сообщение с ошибкой.

Параметр	Тип	Описание
text	string	Текст ошибки

JavaScript
const $checkout = YandexCheckoutUI(123456);
$checkout.toggleLantern('Текст ошибки');

.chargeSuccessful

Сообщает форме об успешном ответе от API ЮKassa.

После вызова этого метода:

сначала будет скрыто сообщение об ошибке (если оно открыто);
потом закроется форма.

JavaScript
const $checkout = YandexCheckoutUI(123456);

// Открываем форму
$checkout.open();

// Токен успешно создан
$checkout.on('yc_success', () => {
    // Запрос к API ЮKassa
    // ...

    // Если оплата прошла успешно, то вызываем метод
    $checkout.chargeSuccessful();
});

.chargeFailful

Сообщает платежной форме о том, что от API ЮKassa пришла ошибка.

После вызова этого метода пользователю показывается сообщение с ошибкой.

Параметр	Тип	Описание
text	string	Текст ошибки

JavaScript
const $checkout = YandexCheckoutUI(123456);

// Открываем форму
$checkout.open();

// Токен успешно создан
$checkout.on('yc_success', () => {
    // Запрос к API ЮKassa
    // ...

    // Оплата не прошла
    $checkout.chargeFailful();
});

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

YandexCheckout.js Платежный токен Проведение платежей Входящие уведомления

Инициализация

Конфигурация

Методы