YandexCheckout.js
YandexCheckout.js — это JavaScript-библиотека, дополнение к API Яндекс.Кассы.
Библиотека позволяет собирать данные банковских карт пользователей на вашей стороне, без необходимости обрабатывать их на ваших серверах. Это значит, что пользователи смогут вводить все данные банковской карты прямо в вашей системе.
С помощью этой библиотеки вы сможете:
  • создавать формы в любом дизайне (например, в вашем стиле и с вашим логотипом);
  • встраивать их в вашу систему так, как вам удобно;
  • проводить тестирование на своей стороне и оптимизировать процесс оплаты.
Инициализация
YandexCheckout.js подключается только с серверов
https://static.yandex.net
. Так чувствительные данные ваших пользователей всегда будут в безопасности.
Чтобы начать работу с API, загрузите основную библиотеку.
HTML
<script src="https://static.yandex.net/checkout/js/v1/"></script>
Аутентификация
Создайте экземпляр объекта YandexCheckout.
Используйте конструкцию
YandexCheckout(<Идентификатор магазина>)
<Идентификатор магазина>
— shopId вашего магазина в Яндекс.Кассе (выдается при подключении, его можно посмотреть в личном кабинете Яндекс.Кассы).
JavaScript
const checkout = YandexCheckout(<Идентификатор магазина>);
После этого можно будет создать инстанс от YandexCheckout и использовать его для генерации токена с данными банковской карты.
Чтобы вы могли создавать платежи с использованием токена, запросите разрешение у вашего менеджера Яндекс.Кассы.
Конфигурация
Вы можете показывать пользователям сообщения и ошибки по-русски или по-английски. По умолчанию Яндекс.Касса отображает ошибки на русском языке.
ПараметрОписаниеТипВалидация
language
Язык пользовательских ошибок. Возможные значения:
en
и
ru
string2 символа
JavaScript
const checkout = YandexCheckout(<Идентификатор магазина>, {
    language: 'en'
});
Токенизация
Сгенерируйте платежный токен с данными банковской карты. Токен можно использовать для проведения оплаты по API Яндекс.Кассы.
JavaScript
checkout.tokenize({
    number: document.querySelector('.number').value,
    cvc: document.querySelector('.cvc').value,
    month: document.querySelector('.expiry_month').value,
    year: document.querySelector('.expiry_year').value
}).then(res => {
    if (res.status === 'success') {
        const { paymentToken } = res.data.response;

        return paymentToken;
    }
});
Параметры метода
ПараметрОписаниеТипВалидация
number
Номер банковской картыstring16 символов, только числа
cvc
Код CVC2 или CVV2, 3 или 4 символа, печатается на обратной стороне картыstring3, 4 символа, только числа
month
Месяц истечения срока действия картыstring2 символа, только числа
year
Год истечения срока действия картыstring2 символа, только числа
Пример валидных данных
JavaScript
checkout.tokenize({
    number: document.querySelector('.number').value,
    cvc: document.querySelector('.cvc').value,
    month: document.querySelector('.expiry_month').value,
    year: document.querySelector('.expiry_year').value
}).then(response => {
    if (response.status === 'success') {
        const { paymentToken } = response.data.response;

        // eyJlbmNyeXB0ZWRNZXNzYWdlIjoiWlc...
        return paymentToken;
    }
});
Пример невалидных данных
JavaScript
checkout.tokenize({
    number: document.querySelector('.number').value,
    cvc: document.querySelector('.cvc').value,
    month: document.querySelector('.expiry_month').value,
    year: document.querySelector('.expiry_year').value
}).then(response => {
    if (response.status === 'error') {
        // validation_error
        const { type } = response.error;

        /*
            [
                {
                    code: 'invalid_expiry_month',
                    message: 'Невалидное значение месяца'
                },
                {
                    code: 'invalid_cvc',
                    message: 'Невалидное значение CVC'
                }
            ]
        */
        const { params } = response.error;

        return response;
    }
});
Ошибки
Библиотека возвращает два типа ошибок: ошибки валидации данных на форме и ошибки, связанные с работой YandexCheckout.js.
JavaScript
try {
    const checkout = YandexCheckout(); // Не передан shopId
} catch(error) {
    // Формат ответа см. в разделе «Ошибки»
}
Формат выдачи ошибок
JavaScript
{
    status: 'error',
    error: {
        type: string,
        message: ?string,
        status_code: number,
        code: ?string,
        params: Array<{
            code: string,
            message: string
        }>
    }
}
Ошибки валидации возникают, когда пользователь неправильно вводит данные банковской карты: эти ошибки необходимо показывать пользователю.
JavaScript
{
    status: 'error',
    error: {
        type: 'validation_error',
        message: undefined,
        status_code: 400,
        code: undefined,
        params: [
            {
                code: 'invalid_number',
                message: 'Неверный номер карты'
            },
            {
                code: 'invalid_expiry_month',
                message: 'Невалидное значение месяца'
            }
        ]
    }
}
Остальные ошибки возвращаются при проблемах с инициализацией библиотеки или взаимодействием библиотеки с сервером Яндекс.Кассы. Такие ошибки показывать пользователю не нужно.
JavaScript
{
    status: 'error',
    error: {
        type: 'api_connection_error',
        message: 'Ошибка в подключении сервера',
        status_code: 402,
        code: 'processing_error',
        params: []
    }
}
Коды ответа
Код ответаЗначение
400Ошибка валидации
401Ошибка аутентификации
402Ошибка подключения к API Яндекс.Кассы
404Запрашиваемый ресурс не найден
500Непредвиденная ошибка
YandexCheckout.js поддерживает стандартные коды ответа:
  • все коды, которые начинаются с
    20*
    , сигнализируют об успешном выполнении запроса;
  • 40*
    — о том, что что-то пошло не так;
  • 50*
    — о том, что произошла какая-то непредвиденная ошибка на стороне Яндекс.Кассы.
Типы ошибок
Тип ошибкиЗначение
authentication_error
Проблема с аутентификацией
api_connection_error
Не получилось установить соединение с Яндекс.Кассой
api_error
Произошла ошибка на стороне Яндекс.Кассы
card_error
Что-то не так с банковской картой
invalid_request_error
Неверные данные запроса
validation_error
Ошибка валидации, какое-то из полей на форме ввода банковской карты введено неверно
Коды ошибок
Код ошибкиЗначение
invalid_number
Невалидный номер карты
invalid_expiry_month
Неверный месяц истечения срока действия карты
invalid_expiry_year
Неверный год истечения срока действия карты
invalid_cvc
Неверный CVC-код
expired_card
Карта просрочена
card_declined
Карта отклонена
processing_error
Ошибка при проверке карты
missing
Непредвиденная ошибка
Что почитать еще
YandexCheckot UIПлатежный токенПроведение платежейВходящие уведомления