Tpay E-commerce Payment Adapter

About

This package is a Tpay payment adapter for `@payloadcms/plugin-ecommerce`, the official e-commerce plugin for Payload CMS 3. It wires a single Tpay merchant account into the plugin's `PaymentAdapter` contract, giving a Polish shop the three payment channels its customers expect: BLIK, pay-by-link bank transfers, and card payments. Where the built-in Stripe adapter would sit, this one sits instead, or alongside it. A checkout runs as a redirect flow. The storefront calls `POST /api/payments/tpay/initiate`, the adapter writes a pending transaction, creates the matching transaction in Tpay, and returns a payment URL. After the customer pays, Tpay calls back on a server-to-server notification endpoint at `/api/payments/tpay/notifications` and also returns the browser. Both paths converge on the same finalization code, which is written to be race-resistant so a double callback never decrements stock twice. The adapter verifies each notification's JWS signature over the full body and, when you supply Tpay's root certificate, checks the certificate chain too. Notifications without a valid security code are refused, never waved through. Configuration is option-driven and every credential falls back to an environment variable, so the adapter throws at startup if `clientId` or `clientSecret` is missing. You can set `payerSuccessUrl` and `payerErrorUrl` to control where Tpay returns the customer, and the README is blunt that skipping them leaves `confirm-order` uncalled, which is the endpoint that decrements inventory. Installing the adapter also adds a `tpay` field group to the plugin's `transactions` collection, so a migration step is required. A `stockClaimedAt` field on that group is how the adapter hands the plugin's stock trigger to exactly one confirmation per transaction, and it is the field to query when reconciling inventory. The adapter is built for Payload 3.83 and newer and tested against 3.88.0, pinned to the 3.x line with no claim of 4.x compatibility. It ships a browser-side counterpart (`tpayAdapterClient`) for the storefront, plus BLIK-specific endpoints that poll transaction state separately from the main confirm flow, because BLIK's six-digit code requires a polling loop rather than a single confirmation. Timeouts cap each Tpay API call at 15 seconds and the certificate fetch at 5, both configurable.

Package info

Package name

@wellmade-online/payload-ecommerce-tpay

Latest version

0.1.0

Unpacked size

224 kB

License

MIT

Weekly downloads

8

Last publish

Sep 14, 2026