Paywiser

Context

Paywiser biedt merchant acquiring en payment gateway-infrastructuur voor kaartbetalingen. Voor WooCommerce-verkopers moet de integratie passen in de orderlifecycle van WooCommerce en asynchrone uitkomsten afhandelen (redirect flows en server-side postbacks) zonder orders in ambigue states achter te laten.

Probleem

Kaartbetalingsflows in WooCommerce hebben een paar non-negotiables:

• Checkout moet orders naar voorspelbare states brengen (pending → paid/failed).
• Redirect-based flows moeten “customer returned” correct afhandelen.
• Server-to-server notificaties moeten geverifieerd worden om tampering te voorkomen.
• Moderne checkout (WooCommerce Blocks) vereist een dedicated integratielaag.

Projectdoelen

• Paywiser aanbieden als volwaardige betaalmethode in WooCommerce-checkout.
• Paywiser’s Redirect- en Hosted-oplossingen ondersteunen vanuit één plugin.
• Postback payloads verifiëren en orderstate deterministisch bijwerken.
• Compatibiliteit behouden met zowel legacy checkout als Blocks checkout.

Beperkingen & Uitdagingen

• De `WC_Payment_Gateway`-lifecycle volgen om brittle checkout behavior te vermijden.
• Postback/return parameters behandelen als untrusted input en verifiëren.
• Afrondingsmismatches voorkomen door bedragen naar de gateway af te stemmen op WooCommerce totalen.
• Configuratie merchant-friendly houden onder `WooCommerce → Settings → Payments`.

Oplossingsoverzicht

We hebben een WooCommerce-gatewayplugin geïmplementeerd die:

• Een nieuwe betaalmethode registreert (`paywiser`) met configureerbare titel/omschrijving.
• Twee gateway-modes ondersteunt: Redirect (hosted pages) en Hosted (kaartgegevens ingevoerd in checkout).
• Transacties naar Paywiser TxHandler verstuurt via HTTP POST naar `https://office.paywiser.com/secure/txHandler.php`.
• Betaalresultaten ontvangt en verifieert via `/wc-api/pw-postback` en de `order-received` return flow.

Architectuur & Technische aanpak

Gatewayconfiguratie

• `sid` en `rcode`
• solution type: `redirect` of `hosted`
• transaction action: `PREAUTH` of `PAYMENT`

Start van checkout

• post een formulier naar TxHandler met totalen, klantvelden, postback URL en redirect URL
• bevat een MD5 request hash voor validatie

Postback-verificatie en orderfinalisatie

De postback handler verifieert de payload met de `vrfy` SHA-256 signature (`sid;rcode;txid;status;amount;currency;tx_action`).

• Succesvolle betalingen finaliseren via `payment_complete(txid)`.
• Mislukte betalingen zetten de order naar `failed` met een diagnostisch bericht.

WooCommerce Blocks-ondersteuning

Blocks-integratie (`checkout.js`) registreert Paywiser als Blocks-betaalmethode met invoerafhandeling en UI.

Technologiestack

• WordPress
• WooCommerce
• PHP (WooCommerce gateway-implementatie)
• JavaScript (Blocks checkout-integratie + invoermaskering voor hosted flow)
• Paywiser TxHandler + postback-verificatie (Acquiring API)

Implementatieproces

1. Redirect vs hosted flows modelleren en mappen naar WooCommerce status-transities.
2. Gateway-instellingen en validatie in wp-admin implementeren.
3. TxHandler POST submission en request hashing implementeren.
4. Geverifieerde postback-afhandeling (`/wc-api/pw-postback`) en return URL verificatie toevoegen.
5. WooCommerce Blocks checkout integreren en end-to-end flows testen voor beide oplossingen.

Resultaten en impact

• WooCommerce-verkopers kunnen Paywiser-kaartbetalingen activeren met een voorspelbare operationele flow.
• Zowel redirect- als hosted oplossingen worden ondersteund vanuit één plugin.
• Server-side postbacks worden geverifieerd vóór de orderstate wordt aangepast.
• Checkout blijft compatibel over WooCommerce legacy en Blocks experiences.

Reflectie

Redirect-based betalingen blijven alleen werkbaar als de server-to-server postback wordt behandeld als bron van waarheid en wordt geverifieerd vóór de orderstate wordt aangepast. Dit vanaf het begin inbouwen voorkomt fraudegevoelig “status via URL parameter”-gedrag en vermindert support load door ambigue uitkomsten.

Samenvatting

Deze plugin integreert Paywiser in WooCommerce met twee ondersteunde betaalmodes, geverifieerde postback-afhandeling en compatibiliteit met zowel legacy- als Blocks checkout flows.