Paywiser

Kontekst

Paywiser ponuja merchant acquiring in payment gateway infrastrukturo za kartična plačila. Za WooCommerce trgovce mora integracija slediti življenjskemu ciklu naročil in obvladati asinhrone izide (redirect tokovi in server-side postbacki) brez dvoumnih stanj.

Problem

Kartični plačilni tokovi v WooCommerce imajo nekaj nespremenljivih zahtev:

• Checkout mora prehajati v predvidljiva stanja (pending → paid/failed).
• Redirect-based tokovi morajo pravilno obravnavati “customer returned”.
• Server-to-server notifikacije je treba verificirati proti manipulaciji.
• Moderen checkout (WooCommerce Blocks) potrebuje ločen integracijski sloj.

Cilji projekta

• Paywiser kot prvovrstna plačilna metoda v WooCommerce checkoutu.
• Podpora Paywiser **Redirect** in **Hosted** rešitvam z enim pluginom.
• Verifikacija postback payloadov in deterministično posodabljanje stanj naročil.
• Kompatibilnost z legacy checkout in Blocks checkout.

Omejitve in izzivi

• Slediti `WC_Payment_Gateway` lifecycle, da checkout ostane stabilen.
• Postback/return parametre obravnavati kot nezaupanja vredne in jih verificirati.
• Izogniti se zaokrožitvenim odstopanjem z usklajenimi zneski z WooCommerce totals.
• Nastavitve ohraniti pregledne in prijazne v `WooCommerce → Settings → Payments`.

Pregled rešitve

Implementirali smo WooCommerce gateway plugin, ki:

• registrira novo plačilno metodo (`paywiser`) z nastavljivim naslovom/opisom
• podpira dva načina: Redirect (kupec se preusmeri na Paywiser plačilne strani) in Hosted (podatki kartice se vnesejo v checkout UI in se pošljejo Paywiserju).
• pošlje transakcije na Paywiser TxHandler prek HTTP POST na `https://office.paywiser.com/secure/txHandler.php`
• prejme in verificira rezultate prek postback endpointa (`/wc-api/pw-postback`) in return URL handlerja na strani `order-received` (kjer je relevantno).

Arhitektura in tehnični pristop

Konfiguracija gatewaya

• `sid` in `rcode`
• tip rešitve: `redirect` ali `hosted`
• akcija transakcije: `PREAUTH` ali `PAYMENT`

Zagon checkouta

• pošlje formo na TxHandler z zneski/valuto, podatki kupca/računa, postback URL in redirect URL
• vključi request hash (MD5) za validacijo zahteve

Postback verifikacija in zaključek naročila

Postback handler verificira payload s podpisom `vrfy` SHA-256 (na osnovi `sid;rcode;txid;status;amount;currency;tx_action`).

• uspešna plačila: `payment_complete(txid)` (različice glede na redirect/hosted)
• neuspešna plačila: status `failed` z diagnostičnim sporočilom

WooCommerce Blocks podpora

Plugin vključuje Blocks integracijo (`checkout.js`) in deklarira kompatibilnost z WooCommerce funkcijami (Cart/Checkout Blocks).

Tehnološki sklad

• WordPress
• WooCommerce
• PHP (WooCommerce gateway implementacija)
• JavaScript (Blocks checkout integracija + input masking za hosted flow)
• Paywiser TxHandler + postback verifikacija (Acquiring API)

Proces implementacije

1. Modeliranje redirect vs hosted tokov in mapiranje v WooCommerce statusne tranzicije.
2. Implementacija gateway nastavitev in validacije v wp-admin.
3. Implementacija TxHandler POST pošiljanja in request hashinga.
4. Dodajanje verificiranega postback handlerja (`/wc-api/pw-postback`) in return URL verifikacije.
5. Integracija WooCommerce Blocks checkout in end-to-end testiranje obeh rešitev.

Rezultati in učinek

• WooCommerce trgovci lahko omogočijo Paywiser kartična plačila s predvidljivim tokom.
• podprti sta redirect in hosted rešitvi
• server-side postbacki so verificirani pred spremembo stanja
• checkout ostaja kompatibilen z legacy in Blocks checkout izkušnjo

Refleksija

Redirect-based plačila so operativno varna le, če je server-to-server postback vir resnice in je pred spremembo stanja verificiran. To prepreči “status po URL parametru” prakse in zmanjša support breme zaradi dvoumnih izidov.

Povzetek

Plugin integrira Paywiser v WooCommerce z dvema podprtima načinoma plačila, verificiranim postbackom in kompatibilnostjo z legacy in Blocks checkout tokovi.