Подключение платёжного шлюза
Платёжный шлюз обрабатывает денежные операции, а сервер Kevmi связывает их с заказами, настройками магазина и уведомлениями. Этот раздел описывает требования к интеграции и проверке состояния.
В этой статье
Проверка доступности#
Kevmi использует API шлюза v3 для создания и восстановления операций, чтения статусов и сверки. Интеграция поддерживает шифрованную передачу карты и банковского кода, оплату по QR через Alipay и СБП, каталог криптомонет и сетей, а также входящие финансовые события.
Поле gateway.configured в GET /api/config показывает, заданы ли обязательные параметры подключения. Этот маршрут не выполняет сетевую проверку шлюза; gateway.connected=false здесь означает отсутствие подтверждённой проверки связи. Для конкретного счёта читайте invoice.availability в GET /api/checkout/{token}: оно учитывает метод, сумму, условия и одобрение магазина. Совместимое поле invoice.gatewayConnected повторяет availability.available и также не является проверкой связи или гарантией одобрения платежа.
Новый платёж и подготовка карточного запроса требуют одобренной последней заявки магазина на проверку сайта. Одобрение само по себе не подключает платёжный шлюз. Если проверка магазина изменилась после отправки платежа, уже созданная операция остаётся доступна для статуса, сверки и запрошенного банковского кода.
Контракт покупательской страницы#
Чувствительные данные шифруются в браузере с RSA-OAEP-256 и A256GCM. Закрытый ключ остаётся на шлюзе. Сервер Kevmi проверяет привязку намерения к счёту и назначению, передаёт пакет и не хранит открытые номер карты, CVV, имя покупателя, email, банковский код или сам пакет.
Перед запуском карт на хост шлюза устанавливается расширение шифрованной передачи. Оно проверяет подпись намерения, срок, повтор, заказ и суммы. Открытого запасного маршрута для реквизитов нет. Это описание механизма защиты, а не заявление о сертификации PCI.
| Маршрут Kevmi | Назначение |
|---|---|
| GET /api/checkout/{token} | Счёт, расчёт, доступность способа и существующий payment |
| POST /api/checkout/{token}/card-intent | Одноразовое намерение и публичный ключ для payment или code |
| POST /api/checkout/{token}/pay | Запуск одной операции; карта передаётся как sealed: {intent,jwe} |
| POST /api/checkout/{token}/code | Шифрованный одноразовый код для текущего запроса банка |
| GET /api/checkout/{token}/status | Чтение прежней операции без нового списания |
| POST /api/checkout/{token}/reconcile | Явная сверка прежней операции |
| GET /api/checkout/{token}/crypto-services | Актуальные монеты, сети и лимиты для счёта USDT |
Размещение и соединение со шлюзом#
Kevmi поддерживает размещение в Sites на Cloudflare Workers с базой D1 и самостоятельное размещение на Node.js с SQLite. Для SQLite нужен постоянный том с резервным копированием. Платёжный шлюз запускается отдельным сервисом со своим постоянным хранилищем.
Для внешнего шлюза задаётся доступный серверу HTTPS origin. В комплекте для самостоятельного размещения сервер обращается к фиксированному сервису шлюза внутри закрытой сети контейнеров; служебный API шлюза не публикуется в интернете. Публичный сайт и обратные вызовы используют HTTPS. Данные карты и банковский код дополнительно зашифрованы в браузере до передачи Kevmi.
localhost обозначает текущий сервер или контейнер; он не предоставляет доступ к компьютеру владельца шлюза. Ключи и секреты соединения хранятся только в серверной конфигурации.
Для собственного домена задайте публичный HTTPS origin в NEXT_PUBLIC_SITE_URL до сборки. Он используется в документации, канонических ссылках и материалах для индексации. Значение содержит только схему и хост с необязательным портом, без пути, параметров, фрагмента и учётных данных. Адрес должен соответствовать APP_ORIGIN серверной конфигурации.
Расчёт и поддерживаемые условия#
В интерфейсе для нового счёта USD доступны карты и Alipay, для RUB — СБП, для USDT — криптовалюта. API для совместимости может сохранить USD + crypto, но такая криптооплата не запускается и возвращает crypto_requires_usdt. USD и USDT различаются; автоматической конвертации или курса 1:1 нет. Для криптооплаты нужен отдельный счёт в USDT.
Для нового реального платежа картой или Alipay текущий шлюз поддерживает только feeCustomerPercent=0 и vatCustomerPercent=100: комиссию полностью покрывает магазин, НДС полностью добавляется покупателю. Остальные доли можно сохранить в счёте и рассчитать, но такой платёж не запускается и получает unsupported_allocation. Сервер не меняет сохранённые условия автоматически. Для СБП и USDT-криптооплаты доступны все доли комиссии; НДС у них отсутствует.
Передача произвольного total_cents не меняет налог провайдера. Несовпадение фактической суммы с сохранённым итогом переводит операцию на проверку и не подтверждает выдачу заказа. Данные business_balance шлюза сохраняются как сведения сверки; они не считаются балансом магазина Kevmi.
Подключение рабочего шлюза#
Подключение включает серверную конфигурацию, проверку выбранных каналов и обработку подтверждённых финансовых событий. Наличие настроек проверяется отдельно от связи с провайдером. Успешный результат платежа принимается после сверки статуса и суммы операции. Инструкции для развёртывания находятся в ops/gateway-integration.md.
- 1
Разверните сервер Kevmi и шлюз отдельными сервисами. Настройте постоянное хранилище, резервное копирование и необходимые фоновые процессы.
- 2
Для внешнего подключения задайте HTTPS origin в GATEWAY_BASE_URL. Комплект самостоятельного размещения использует настроенный внутренний сервис. В обоих случаях нужны серверный GATEWAY_API_KEY и отдельный GATEWAY_WEBHOOK_SECRET; секреты не передаются браузеру.
- 3
На шлюзе задайте BACKEND_WEBHOOK_URL с путём /api/gateway/webhook и совпадающий BACKEND_WEBHOOK_SECRET.
- 4
Включите шифрованную передачу карт и сохраните закрытый ключ исключительно на хосте шлюза. Проверьте доступность публичного ключа и совпадение параметров подписи намерений.
- 5
Проверьте готовность каналов, ограничения и одобрение сайта магазина перед запуском.