Tpay E-commerce Payment Adapter

Описание

Пакет реализует контракт PaymentAdapter из `@payloadcms/plugin-ecommerce` и подключает один мерчант-аккаунт Tpay к магазину на Payload CMS 3. Покупателям доступны три способа оплаты: BLIK, pay-by-link банковские переводы и оплат картой. Адаптер работает как замена или дополнение к встроенному Stripe-адаптеру. Оформление заказа идёт через redirect-флоу. Витрина вызывает `POST /api/payments/tpay/initiate`, адаптер создаёт транзакцию в статусе pending, формирует параллельную транзакцию в Tpay и возвращает paymentUrl. После оплаты Tpay присылает серверное уведомление на эндпоинт `/api/payments/tpay/notifications` и одновременно возвращает браузер покупателя. Оба пути сходятся в один блок финализации, защищённый от гонок: двойной колбэк не списывает склад дважды. Адаптер проверяет JWS-подпись тела уведомления через заголовок X-JWS-Signature и, если указан корневой сертификат Tpay, дополнительно проверяет цепочку. Уведомления без валидного security code отклоняются. Конфигурация передаётся через опции, и каждый ключ имеет fallback в переменные окружения: `TPAY_CLIENT_ID`, `TPAY_CLIENT_SECRET`, `TPAY_MERCHANT_ID`, `TPAY_SECURITY_CODE`, `TPAY_SANDBOX`. Если `clientId` или `clientSecret` не заданы, адаптер выбрасывает ошибку при запуске. Поля `payerSuccessUrl` и `payerErrorUrl` управляют адресами возврата покупателя. Без них эндпоинт `confirm-order`, который списывает остатки на складе, не вызывается. При установке адаптер добавляет группу полей `tpay` (transactionId, title, paymentUrl, shippingAddress, stockClaimedAt) в коллекцию `transactions`, поэтому требуется миграция. Поле `stockClaimedAt` гарантирует, что триггер списания склада сработает ровно один раз на транзакцию, и его удобно использовать при сверке остатков. Адаптер поддерживает Payload 3.83.0 и новее, протестирован на 3.88.0, ограничен линейкой 3.x без заявлений о совместимости с 4.x. В пакет входит клиентский модуль `tpayAdapterClient` для витрины и отдельные эндпоинты для поллинга статуса BLIK-транзакций, поскольку шестизначный код BLIK требует цикла опроса, а не единичного подтверждения. Таймауты вызовов к API Tpay по умолчанию 15 секунд, запрос сертификата 5 секунд, оба значения настраиваются.

О пакете

Имя пакета

@wellmade-online/payload-ecommerce-tpay

Последняя версия

0.1.0

Размер

224 кБ

Лицензия

MIT

Загрузок в неделю

9

Последняя публикация

14 сент. 2026 г.