Checkout.js подключается только с серверов
https://static.yoomoney.ru
. Так чувствительные данные ваших пользователей всегда будут в безопасности.Чтобы начать работу с API, загрузите основную библиотеку.
<script src="https://static.yoomoney.ru/checkout-js/v1/checkout.js"></script>
Создайте экземпляр объекта YooMoneyCheckout.
Используйте конструкцию
YooMoneyCheckout (<Идентификатор магазина>)
<Идентификатор магазина>
— shopId вашего магазина в ЮKassa (выдается при подключении, его можно посмотреть в личном кабинете ЮKassa).
const checkout = YooMoneyCheckout(<Идентификатор магазина>);
После этого можно будет создать инстанс от YooMoneyCheckout и использовать его для генерации токена с данными банковской карты.
Вы можете показывать пользователям сообщения и ошибки по-русски или по-английски.
По умолчанию ЮKassa отображает ошибки на русском языке.
Параметр | Описание | Тип | Валидация |
---|---|---|---|
language | Язык пользовательских ошибок. Возможные значения: en и ru | string | 2 символа |
const checkout = YooMoneyCheckout(<Идентификатор магазина>, { language: 'en' });
Сгенерируйте платежный токен с данными банковской карты. Токен можно использовать для проведения оплаты по API ЮKassa.
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 | Номер банковской карты | string | 16 символов, только числа |
cvc | Код CVC2 или CVV2, 3 или 4 символа, печатается на обратной стороне карты | string | 3, 4 символа, только числа |
month | Месяц истечения срока действия карты | string | 2 символа, только числа |
year | Год истечения срока действия карты | string | 2 символа, только числа |
Пример валидных данных
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; } });
Пример невалидных данных
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.
try { const checkout = YooMoneyCheckout(); // Не передан shopId } catch(error) { // Формат ответа см. в разделе «Ошибки» }
Формат выдачи ошибок
{ status: 'error', error: { type: string, message: ?string, status_code: number, code: ?string, params: Array<{ code: string, message: string }> } }
Ошибки валидации возникают, когда пользователь неправильно вводит данные банковской карты: эти ошибки необходимо показывать пользователю.
{ status: 'error', error: { type: 'validation_error', message: undefined, status_code: 400, code: undefined, params: [ { code: 'invalid_number', message: 'Неверный номер карты' }, { code: 'invalid_expiry_month', message: 'Невалидное значение месяца' } ] } }
Остальные ошибки возвращаются при проблемах с инициализацией библиотеки или взаимодействием библиотеки с сервером ЮKassa.
Такие ошибки показывать пользователю не нужно.
{ 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Проведение платежа с использованием токенаОсновы проведения платежейВходящие уведомления