Docs
API ЮKassa
Инструкции
Старые версии API
Помощь
Подключить ЮKassa

Справочник параметров, методов и кодов ошибок

В этом справочнике описаны:
  • Параметры, которые передаются при инициализации виджета;
  • Ошибки, связанные с инициализацией виджета;
  • Методы виджета;
  • События виджета.
Описание параметров для инициализации виджета
Описание параметров, которые необходимо передать в экземпляр класса YooMoneyCheckoutWidget на странице оплаты для инициализации виджета.
ПараметрТипОбязательностьОписание
confirmation_tokenstringОбязательныйТокен ЮKassa для инициализации виджета. Чтобы получить токен, нужно создать платеж
return_url
string
Необязательный
Адрес страницы, на которую пользователь вернется после завершения оплаты. Адрес должен быть абсолютным (с указанием протокола и домена сайта). Пример: https://example.com/return_url.
Если адрес страницы не передан, необходимо обработать события процесса оплаты
error_callback(error) => voidОбязательныйCallback-функция, которая принимает код ошибки инициализации
customizationobjectНеобязательныйНастройка платежной формы. Сейчас можно настроить способ отображения платежной формы, цветовую схему и отображение способов оплаты.
modal
boolean
Необязательный
Передается в customization.
Настройка способа отображения платежной формы. Возможные значения:
colors
object
Необязательный
Передается в customization.
Настройка цветовой схемы. В объекте передаются цвета, которые нужно изменить в интерфейсе платежной формы.
payment_methods
array
Необязательный
Передается в customization.
  • bank_card — банковская карта;
  • yoo_money — ЮMoney (кошелек, привязанные карты и баллы лояльности);
  • mir_pay — Mir Pay;
  • sber_loan — «Покупки в кредит» от СберБанка;
  • sberbank — SberPay;
  • sbp — СБП (Система быстрых платежей);
  • tinkoff_bank — T-Pay.

Если хотите настраивать отображение способов оплаты, напишите вашему менеджеру ЮKassa.

Описание параметров для настройки цветовой схемы
Описание всех параметров объекта colors, которые можно использовать для настройки цветовой схемы.
Для тех, кто настраивает отображение способов оплаты: если на платежной форме виджета ЮKassa вы отображаете только Mir Pay или банковскую карту с Mir Pay, то вместо блока способа оплаты Mir Pay будет отображаться кнопка. Цветовую схему этой кнопки изменить нельзя — ее фон может быть только белым.
ПараметрТипОписаниеПо умолчанию
control_primarystringЦвет фона акцентных элементов: кнопка Заплатить, выбранные переключатели, опции, граница выбранного текстового поля. Рекомендуется использовать яркий цвет, привлекающий внимание#FFCC00 (желтый)
control_primary_contentstringЦвет текста в кнопке Заплатить и содержимого акцентных переключателей и опций (например, выставленный флажок). Рекомендуется использовать цвет, контрастный к control_primary.
Если параметр не передан, цвет рассчитывается на основе control_primary
#000000 (черный) или #FFFFFF (белый) — выбирается контрастный к control_primary
backgroundstringЦвет фона платежной формы, цвет сообщений об ошибках и подсказок. Рекомендуется использовать цвет, близкий к цвету фона контейнера, в котором размещен виджет#FFFFFF (белый)
textstringЦвет всех текстов на платежной форме, кроме текстов в кнопке Заплатить и во всплывающих подсказках.
Если параметр не передан, цвет рассчитывается на основе background
Контрастный к background
borderstringЦвет границ и разделителей.
Если параметр не передан, цвет рассчитывается на основе background
Контрастный к background
control_secondarystringЦвет неакцентных элементов интерфейса.
Если параметр не передан, цвет рассчитывается на основе background
Контрастный к background
Ошибки инициализации виджета
Если инициализация виджета закончилась неудачей, ЮKassa передаст в callback-функцию код ошибки.
Код ошибкиОписание
customization_of_payment_methods_not_allowedЭтот магазин не может использовать параметр payment_methods. Если хотите настраивать отображение способов оплаты, напишите вашему менеджеру ЮKassa.
internal_service_errorПри создании платежа возникла ошибка. Повторите инициализацию виджета
invalid_combination_of_payment_methodsНедопустимое сочетание способов оплаты в payment_methods объекта customization. Одновременно можно передавать только bank_card и mir_pay, если вам разрешено настраивать отображение способов оплаты.
invalid_payment_methodsНекорректное значение payment_methods объекта customization. В массиве можно передать коды только тех способов оплаты, которые поддерживает виджет. Если отображаете несколько способов, их коды нужно перечислять через запятую.
invalid_return_urlНекорректный URL возврата. При инициализации виджета передайте в return_url абсолютный URL страницы завершения оплаты, указав в нём протокол и домен вашего сайта
invalid_tokenНеверный токен. Для получения токена создайте платеж
no_payment_methods_to_display
Отсутствуют способы оплаты для отображения: например, вы не можете принимать платежи выбранным способом или способ оплаты не поддерживает выбранные вами опции проведения платежа (оплату в две стадии, автоплатежи).
При инициализации виджета передайте в payment_methods другой способ оплаты
token_expiredИстек срок действия токена. Для получения нового токена создайте платеж
token_requiredТокен не передан. При инициализации виджета передайте confirmation_token
Описание методов виджета
МетодТипОписание
render
(id?: string) => Promise<undefined>
Отображение платежной формы. Исполнение Promise говорит о полной загрузке платежной формы. Promise можно не использовать.
Если вы размещаете виджет на странице оплаты, в параметрах метода передайте значение атрибута id контейнера, в котором нужно разместить платежную форму. Если хотите отображать виджет во всплывающем окне, в параметрах метода ничего передавать не нужно.
destroy() => voidУдаление инициализированного виджета.
on(event, callback) => voidРегистрация события виджета и вызов callback-функции.
Описание событий виджета
Виджет может уведомлять о следующих событиях:
СобытиеОписание
successПользователь успешно завершил оплату. Используется совместно с fail
failПользователь неудачно завершил оплату. Используется совместно с success
completeПользователь завершил оплату. Событие наступает после успешной или неудачной оплаты.
modal_closeПользователь закрыл всплывающее окно с платежной формой. Для тех, кто отображает виджет во всплывающем окне.
Что почитать еще
© 2025, ООО НКО «ЮМани»