Словарь терминов
В платёжном коде много своих слов. Здесь каждое из них объяснено простым языком. В остальных разделах эти слова больше не расшифровываются, поэтому возвращайтесь сюда, если что-то непонятно.
Участники
Покупатель. Человек, который платит.
Мерчант (продавец). Вы — компания, которая что-то продаёт и получает деньги.
Сервер мерчанта (API мерчанта). Ваш бэкенд. Он знает настоящие цены, хранит секретные ключи, общается с платёжным провайдером и решает, оплачен ли заказ. Браузер никогда не решает это сам.
Платёжный провайдер (PSP). Компания, через которую проходят деньги: Stripe, Adyen, PayPal, банк и т. д. PSP — сокращение от «payment service provider».
Банк-эквайер (эквайринг). Банк, который принимает оплату картами для продавца. Некоторые банки делают это напрямую, без посредника вроде Stripe.
Хост (приложение-хост). Приложение, внутри которого работает оплата: ваш сайт, React-приложение или мобильное приложение, которое показывает оплату во встроенном браузере (WebView).
Части checkout kit
Движок (engine). Главный объект из @checkout-kit/core. Создаётся функцией createCheckout(). Проводит оплату по шагам: создаёт платёж, отправляет платёжные данные, выполняет дополнительные шаги и получает результат.
Headless («без интерфейса»). У движка нет визуальной части. Он не рисует кнопки и формы. Интерфейс вы делаете сами или берёте необязательный пакет @checkout-kit/ui.
Плагин провайдера (адаптер). Пакет, который учит движок работать с одним платёжным провайдером. Например, @checkout-kit/provider-stripe знает форматы запросов и ответов Stripe. Сам движок про конкретных провайдеров ничего не знает.
Runtime и раннеры (runners). Раннер — код, который выполняет один вид дополнительного шага в браузере: открывает страницу банка, показывает QR-код, запускает SDK провайдера. В @checkout-kit/runtime-browser лежат готовые раннеры для браузера.
Место для показа (mount). Элемент на странице, куда раннер может что-то вывести, например страницу банка во фрейме. В React его создаёт компонент PaymentActionHost.
Снимок состояния (snapshot). Состояние движка в текущий момент: на каком он шаге, данные платежа, ошибка. React-хуки читают снимок и перерисовывают компонент, когда он меняется.
Фаза (phase). Текущий шаг движка, например «создание», «ожидание действия» или «успешно».
Сам платёж
Платёж (intent). Одна запись о платеже у провайдера. У неё есть id, сумма, валюта и статус. Название пришло из Stripe (PaymentIntent), но движок использует его для всех провайдеров.
Платёжный инструмент (instrument). То, чем платит покупатель: токен карты, токен кошелька или ничего ({ kind: 'none' }), если провайдер сам собирает данные на своей странице.
Токен. Безопасная замена данных карты. Форма провайдера сама принимает номер карты и возвращает короткую строку, например pm_123. Вы отправляете эту строку вместо номера карты, и настоящие данные карты не попадают в ваш код.
Попытка оплаты (attempt). Одна попытка заплатить. Если сеть оборвалась посередине, повторяется та же попытка. Новая попытка начинается, только когда предыдущая точно закончилась.
Ключ идемпотентности (idempotency key). Уникальная строка, которую вы прикрепляете к попытке. Если один и тот же запрос пришёл дважды (например, ответ потерялся и запрос отправили снова), сервер видит тот же ключ и возвращает первый результат, а не списывает деньги повторно.
Действие (action). Дополнительный шаг, который провайдер просит выполнить, прежде чем закончить оплату. Например: подтвердить оплату на странице банка, ввести одноразовый код, отсканировать QR-код. Движок останавливается и ждёт, пока хост выполнит действие.
Подтверждение шага (evidence). То, что вернулось после действия: параметры в адресе после перенаправления, сообщение из фрейма, ответ SDK. Это лишь знак, что покупатель прошёл шаг, и не доказательство оплаты. После этого движок всегда спрашивает у провайдера настоящий статус.
Списание (capture). Фактическое списание денег. Некоторые платежи сначала только резервируют (авторизуют) деньги, а списывают позже. В большинстве примеров здесь списание происходит автоматически.
В обработке (processing). Провайдер принял платёж, но окончательного результата ещё нет. Движок проверяет статус позже, а не создаёт новый платёж.
Окончательный статус. Результат, который уже не изменится: успешно, отказ, отменено или ошибка.
Дополнительные шаги в браузере
Перенаправление (redirect). Браузер уходит с вашей страницы на другой сайт (например, на страницу банка), а потом возвращается на ваш адрес возврата.
Адрес возврата (return URL). Страница вашего сайта, куда покупатель возвращается после перенаправления. По этому адресу должно открываться ваше приложение и вызывать engine.hydrate().
Восстановление (hydrate). Продолжение оплаты после перезагрузки страницы или возврата с сайта банка. Перед уходом со страницы движок сохраняет несколько id в session storage. hydrate() читает их и спрашивает у провайдера настоящий результат.
Session storage. Хранилище браузера, которое живёт, пока открыта вкладка. Движок хранит там только id — никогда данные карты или секреты.
Фрейм (iframe). Страница, показанная внутри вашей страницы. Банки часто показывают так свою страницу подтверждения.
3-D Secure (3DS). Проверка карты банком покупателя: одноразовый код, push-уведомление в банковском приложении и т. п. Ещё это называют challenge (проверка). 3DS1 — старая версия, 3DS2 — текущая.
SDK. JavaScript-библиотека провайдера, например Stripe.js. Показывает поля карты или кнопки кошелька от самого провайдера.
Поля провайдера (hosted fields). Поля карты, которые провайдер показывает во фрейме на вашей странице. Ваш код никогда не видит номер карты.
Платёжная страница провайдера (HPP). Целая страница оплаты на сайте провайдера. Покупателя перенаправляют туда, а потом возвращают обратно.
Кошелёк (wallet). Apple Pay, Google Pay и похожие сервисы, которые платят сохранённой картой.
Опрос статуса (polling). Повторные запросы статуса каждые несколько секунд, пока результат не станет известен. Используется, например, при оплате по QR-коду.
Источник (origin). Схема, домен и порт сайта, например https://shop.example:443. Браузер по нему решает, какой сайт с каким может общаться. Движок принимает сообщения только из ожидаемых источников.
Сервер
Вебхук (уведомление, webhook). Запрос, который провайдер сам отправляет на ваш сервер, когда меняется статус платежа. Работает, даже если покупатель закрыл браузер. Сервер обязан проверить, что вебхук настоящий (например, по подписи HMAC).
Выдача заказа (fulfillment). То, что покупатель получает за оплату: отправка товара, открытие доступа и т. д. Делайте это только на сервере и только после подтверждённой оплаты.
Сверка (reconciliation). Сравнение ваших записей с записями провайдера и исправление расхождений. Например, поиск платежа, который прошёл, пока у покупателя был закрыт браузер.
Тестирование
Песочница (sandbox). Тестовый аккаунт у настоящего провайдера. Настоящий API, ненастоящие деньги.
Симулятор (mock). Локальный поддельный провайдер на вашем компьютере. Не нужен ни аккаунт, ни ключи. Подходит для разработки, но не заменяет проверку в песочнице.
Фикстура (fixture). Заранее подготовленные тестовые данные, например сохранённый ответ провайдера.
Тесты соответствия (conformance). Готовый набор тестов из @checkout-kit/conformance. Каждый плагин провайдера должен их пройти. Они проверяют, что плагин соблюдает правила движка.
Мобильные приложения
WebView. Встроенный браузер внутри приложения для iOS или Android. Приложение может показать в нём веб-страницу оплаты.
Мост (bridge). Канал сообщений между веб-страницей в WebView и самим приложением. Его даёт пакет @checkout-kit/webview-bridge.
Deep link. Ссылка, которая открывает определённый экран в приложении, например mybank://pay?id=1.