Окружение симулятора

English

Здесь показано, как запустить шесть протоколов-примеров. Для Stripe, Adyen, PayPal и их официальных SDK вместо этого читайте быстрый старт и сервер мерчанта.

Запуск демо

Нужны Node.js 24 и npm:

npm ci
npm run dev:mock
# In another terminal:
npm run dev:bank

1. Один раз откройте https://localhost:5100/ и примите локальный сертификат. Это поддельный банк.
2. Потом откройте адрес демо, который Vite вывел в терминал.

На запросы к «вашему серверу» отвечает MSW-воркер в браузере. Страницы банка работают на своём HTTPS-origin. Ключи аккаунтов не нужны. В демо на сайте есть оба симулятора.

Тестовые карты:

Карта	Результат
4242 4242 4242 4242	Одобрено.
4000 0000 0000 0002	Отказ.
4000 0000 0000 9995	Недостаточно средств.
4000 0025 0000 3155	Проверка банком проходит.
4000 0084 0000 1629	Проверка банком не проходит.
4000 0000 0000 9979	Сначала в обработке, потом оплачено.

В примерах платёжной страницы и кошелька результат выбирается в симуляторе, а не вводом карты. В разделе тестирование описано, как работают состояние симулятора и восстановление.

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

Установите пакеты из npm вместе с зависимостями. Веб-приложению нужны core, браузерный runtime и провайдер. Для React 19 добавьте связку с React и, по желанию, UI. Список пакетов описывает все пакеты.

Импортируйте @checkout-kit/ui/styles.css и оберните оплату в CheckoutRoot (или в элемент с классом .ck-root). С Tailwind сохраняйте такой порядок слоёв:

@layer theme, base, components, checkout, utilities;
@import 'tailwindcss/theme.css' layer(theme);
@import 'tailwindcss/preflight.css' layer(base);
@import '@checkout-kit/ui/styles.css';
@import 'tailwindcss/utilities.css' layer(utilities);

Полезно знать:

• пакеты — ESM. Тип настроек регистрирует id провайдера для TypeScript, а динамический импорт загружает код;
• в core нет кода для браузера; браузерный runtime создавайте в клиентском коде;
• библиотека читает только переданные ей настройки, а не переменные окружения;
• переменные VITE_ публичные. Секреты провайдера остаются на вашем сервере;
• baseUrl должен указывать на ваш API; используйте точные origin банка и фреймов;
• не включайте поддельный MSW-воркер из демо в настоящую оплату.

Страница возврата

• Если сайт работает из подпапки, укажите её в returnPath.
• Передайте движку runtime.runners, runtime.storage и runtime.returnUrl.
• По этому пути должно открываться ваше приложение и вызывать hydrate с runtime.readReturnParams().
• Шагам во фрейме нужно место для показа (место для шагов на странице). Кошельку нужен адаптер SDK.

Файл настройки демо · Работа в браузере · Решение проблем