Tpay E-commerce Payment Adapter

Über

Dieses Paket ist ein Tpay-Zahlungsadapter für `@payloadcms/plugin-ecommerce`, das offizielle E-Commerce-Plugin für Payload CMS 3. Es bindet ein einzelnes Tpay-Händlerkonto in den PaymentAdapter-Vertrag des Plugins ein und stellt drei Zahlungswege bereit: BLIK, Pay-by-Link-Banküberweisungen und Kartenzahlungen. Der Adapter ist als Drop-in-Alternative zum Stripe-Adapter konzipiert und lässt sich an dessen Stelle oder parallel dazu betreiben. Der Checkout läuft als Redirect-Flow ab. Der Storefront ruft `POST /api/payments/tpay/initiate` auf, der Adapter legt eine ausstehende Transaktion an, erzeugt die entsprechende Transaktion bei Tpay und gibt eine Payment-URL zurück. Nach der Zahlung sendet Tpay eine Server-to-Server-Benachrichtigung an den Endpoint `/api/payments/tpay/tpay/notifications` und liefert den Browser zurück. Beide Pfade laufen in derselben Finalisierungslogik zusammen, die gegen Race Conditions abgesichert ist. Ein doppelter Callback führt nie zu einer doppelten Bestandsminderung. Der Adapter verifiziert die JWS-Signatur über den gesamten Body der Benachrichtigung und prüft bei Angabe des Tpay-Root-Zertifikats ebenfalls die Zertifikatskette. Benachrichtigungen ohne gültigen Security Code werden abgewiesen. Die Konfiguration erfolgt über Optionen, wobei sich jeder Berechtigungsnachweis auf eine Umgebungsvariable zurückfallen lässt (`TPAY_CLIENT_ID`, `TPAY_CLIENT_SECRET`, `TPAY_MERCHANT_ID`, `TPAY_SECURITY_CODE`, `TPAY_SANDBOX`). Fehlen `clientId` oder `clientSecret` beim Start, wirft der Adapter einen Fehler. Mit `payerSuccessUrl` und `payerErrorUrl` wird festgelegt, wohin Tpay den Kunden zurückleitet. Ohne diese URLs bleibt der `confirm-order`-Endpoint ungesetzt, was zur Folge hat, dass der Lagerbestand nicht abgezogen wird. Bei der Installation fügt der Adapter dem `transactions`-Collection des Plugins eine `tpay`-Feldgruppe hinzu, die die Felder `transactionId`, `title`, `paymentUrl`, `shippingAddress` und `stockClaimedAt` umfasst. Eine Migration ist erforderlich. Das Feld `stockClaimedAt` ist der Mechanismus, der dem Stock-Trigger des Plugins genau eine Bestätigung pro Transaktion zuweist und der Anlaufpunkt bei der Lagerabstimmung ist. Der Adapter ist für Payload 3.83 und neuer gebaut und gegen 3.88.0 getestet, mit Pinning auf die 3.x-Linie ohne Aussicht auf 4.x-Kompatibilität. Mitgeliefert wird ein browserseitiger Client (`tpayAdapterClient`) für den Storefront sowie separate BLIK-spezifische Endpoints, die den Transaktionsstatus unabhängig vom regulären Bestätigungs-Flow pollen, da die sechsstellige BLIK-Zahlung ein Polling erfordert statt einer einzelnen Bestätigung. Timeouts sind pro Tpay-API-Aufruf auf 15 Sekunden und für den Zertifikatsabruf auf 5 Sekunden begrenzt, beide konfigurierbar.

Paketinformationen

Paketname

@wellmade-online/payload-ecommerce-tpay

Neueste Version

0.1.0

Entpackte Größe

224 kB

Lizenz

MIT

Wöchentliche Downloads

9

Zuletzt veröffentlicht

14. Sep. 2026