Решение проблем

English

Сначала соберите основные сведения: фаза движка, провайдер, id платежа (intent), вид шага (action) и код ошибки. Затем посмотрите соответствующий запрос к вашему серверу.

Никогда не пишите в логи поля карты, токены, клиентские секреты и необработанные ответы SDK.

Установка и настройка

Проблема	Что проверить и как исправить
npm не может скачать зависимость checkout-kit	Используйте полное имя @checkout-kit/* и публичный реестр. Уберите старую настройку @checkout-kit:registry, указывающую на GitHub Packages, из npm-конфига проекта/пользователя. Проверьте npm view @checkout-kit/core version --registry=https://registry.npmjs.org. См. установку.
У интерфейса нет стилей	Импортируйте @checkout-kit/ui/styles.css и оберните оплату в CheckoutRoot (или в элемент с классом .ck-root).
window is not defined при SSR	Создавайте runtime и мост только в браузере. Компоненты React и UI можно импортировать и рендерить на сервере.
Неизвестный провайдер	Импортируйте тип его настроек и зарегистрируйте провайдера с его настоящим id и модулем.
Нет cookie / запрос к API не проходит	Проверьте baseUrl, origin, credentials, имя хоста и то, что у покупателя есть сессия.

Дополнительные шаги (actions)

Проблема	Что проверить и как исправить
Шаг ждёт, но ничего не показано	Добавьте PaymentActionHost или вызовите runPendingAction сами.
Негде показать шаг (нет mount)	Для шагов во фрейме и на странице используйте createMount(element) и не скрывайте этот элемент.
Нет адаптера SDK	Имя sdk у адаптера должно совпадать с action.sdk. См. настройку провайдера.
SDK возвращает результат слишком рано	Возвращайте результат из обработчика «готово» или «дополнительные данные» в SDK, а не в момент появления компонента.
Конфликт integrity	Один адрес скрипта и один хеш на сессию. Перед изменением перезагрузите страницу.
Ответ из фрейма игнорируется	Проверьте точный origin, отправителя, тип сообщения и id шага. Не разрешайте «любой источник» (*).
Неподдерживаемый шаг	Включите только те способы оплаты, которые поддерживаете, или реализуйте тип шага, который вернул провайдер.
Оплата по QR никогда не завершается	Проверьте статус на сервере, уведомления и опрос статуса. Сканирование кода не доказывает оплату.

Восстановление и статус

Проблема	Что проверить и как исправить
Страница возврата отдаёт 404	Приложение должно открываться ровно по адресу возврата на опубликованном сайте.
Сохранённый платёж не найден	Передайте движку runtime.storage. Оставайтесь в той же вкладке. Не вызывайте reset() до hydrate().
Сервер недоступен во время восстановления	Сохраните параметры и снова вызовите hydrate, когда сервер заработает.
Обработка не заканчивается	Проверьте тот же платёж, прежде чем разрешать новое списание.
Stripe capture_required	Спишите деньги на своём сервере. В примере используется автоматическое списание.
PayPal capture_unverified	Возвращайте проверенный статус списания, сумму и валюту, а не только статус заказа.
Adyen Pending / Received	Проверьте подпись вебхука (HMAC), аккаунт, порядок событий и то, что сохранено на сервере.
Данные от другого заказа / неверные данные	Используйте сохранённый шаг именно этого заказа.
HTTP 409 при повторном запросе	Данные изменились, а ключ операции остался прежним. Посмотрите первый результат для этого ключа.
Кнопка повтора остаётся неактивной	isLocked равен true и в окончательных состояниях. Добавьте своё условие для восстановления.

Мобильные приложения (нативный мост)

• Используйте сессию из сообщения PAYMENT_READY и давайте каждой команде уникальный id.
• Собирайте внедряемые команды через createBridgeCommand / createCommandScript. Они безопасно экранируют данные.
• Старые и повторные команды игнорируются. На ping приходит ответ с соответствующими данными о готовности.
• В onMessage принимайте сообщения только с адреса своей страницы оплаты.
• Даже если WebView разрешено открыть страницу банка, эта страница не может отдавать команды вашему приложению.
• Когда приложение получает ссылку возврата со своей схемой, передавайте её данные как PAYMENT_RESUME, а не открывайте этот адрес в WebView.

Пример мобильного приложения сохраняет ссылки возврата, пришедшие до установления связи, и показывает, как обрабатывать навигацию. Браузерные тесты не заменяют настоящую сборку под iOS или Android.

Где именно сбой

Запустите npm run dev:integration, чтобы сравнить свою настройку с локальным симулятором.

• Если с симулятором всё работает, проблема в настройках песочницы, вашем сервере или настройке SDK.
• Если и симулятор не работает, запустите тесты затронутого пакета и тесты контракта.