Инструкции
Помощь
Подключить ЮKassa
Использование Checkout.js
Инициализация
Checkout.js подключается только с серверов https://static.yoomoney.ru. Так чувствительные данные ваших пользователей всегда будут в безопасности.
Чтобы начать работу с API, загрузите основную библиотеку.
HTML
<script src="https://static.yoomoney.ru/checkout-js/v1/checkout.js"></script>
Аутентификация
Создайте экземпляр объекта YooMoneyCheckout.
Используйте конструкцию YooMoneyCheckout (<Идентификатор магазина>)
<Идентификатор магазина>
 — shopId вашего магазина в ЮKassa (выдается при подключении, его можно посмотреть в личном кабинете ЮKassa).
JavaScript
const checkout = YooMoneyCheckout(<Идентификатор магазина>);
После этого можно будет создать инстанс от YooMoneyCheckout и использовать его для генерации токена с данными банковской карты.
Конфигурация
Вы можете показывать пользователям сообщения и ошибки по-русски или по-английски. По умолчанию ЮKassa отображает ошибки на русском языке.
ПараметрОписаниеТипВалидация
languageЯзык пользовательских ошибок. Возможные значения: en и rustring2 символа
JavaScript
const checkout = YooMoneyCheckout(<Идентификатор магазина>, {
    language: 'en'
});
Токенизация
Сгенерируйте платежный токен с данными банковской карты. Токен можно использовать для проведения оплаты по API ЮKassa.
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;
    }
});
Ошибки
Библиотека возвращает два типа ошибок: ошибки валидации данных на форме и ошибки, связанные с работой Checkout.js.
JavaScript
try {
    const checkout = YooMoneyCheckout(); // Не передан 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: 'Невалидное значение месяца'
            }
        ]
    }
}
Остальные ошибки возвращаются при проблемах с инициализацией библиотеки или взаимодействием библиотеки с сервером ЮKassa. Такие ошибки показывать пользователю не нужно.
JavaScript
{
    status: 'error',
    error: {
        type: 'api_connection_error',
        message: 'Ошибка в подключении сервера',
        status_code: 402,
        code: 'processing_error',
        params: []
    }
}
Коды ответа
Код ответаЗначение
400Ошибка валидации
401Ошибка аутентификации
402Ошибка подключения к API ЮKassa
404Запрашиваемый ресурс не найден
500Непредвиденная ошибка
Checkout.js поддерживает стандартные коды ответа:
  • все коды, которые начинаются с 20*, сигнализируют об успешном выполнении запроса;
  • 40* — о том, что что-то пошло не так;
  • 50* — о том, что произошла какая-то непредвиденная ошибка на стороне ЮKassa.
Типы ошибок
Тип ошибкиЗначение
authentication_errorПроблема с аутентификацией
api_connection_errorНе получилось установить соединение с ЮKassa
api_errorПроизошла ошибка на стороне ЮKassa
card_errorЧто-то не так с банковской картой
invalid_request_errorНеверные данные запроса
validation_errorОшибка валидации, какое-то из полей на форме ввода банковской карты введено неверно
Коды ошибок
Код ошибкиЗначение
invalid_numberНевалидный номер карты
invalid_expiry_monthНеверный месяц истечения срока действия карты
invalid_expiry_yearНеверный год истечения срока действия карты
invalid_cvcНеверный CVC-код
processing_errorОшибка при проверке карты
missingНепредвиденная ошибка
Что почитать еще
Виджет ЮKassaПроведение платежа с использованием токенаОсновы проведения платежейВходящие уведомления