Paywiser

Kontekst

Paywiser nudi merchant acquiring i payment gateway infrastrukturu za kartična plaćanja. Za WooCommerce trgovce integracija mora slijediti životni ciklus narudžbi i pokriti asinkrone ishode (redirect tokovi i server-side postbackovi) bez dvosmislenih statusa.

Problem

Kartični tokovi plaćanja u WooCommerceu imaju nekoliko nepromjenjivih zahtjeva:

• Checkout mora prelaziti u predvidljive statuse (pending → paid/failed).
• Redirect-based tokovi moraju pravilno obrađivati “customer returned”.
• Server-to-server notifikacije treba verificirati protiv manipulacije.
• Moderni checkout (WooCommerce Blocks) zahtijeva zaseban integracijski sloj.

Ciljevi projekta

• Paywiser kao prvoklasna metoda plaćanja u WooCommerce checkoutu.
• Podrška Paywiser **Redirect** i **Hosted** rješenjima u jednom pluginu.
• Verifikacija postback payloadova i determinističko ažuriranje statusa narudžbi.
• Kompatibilnost s legacy checkoutom i Blocks checkoutom.

Ograničenja i izazovi

• Slijediti `WC_Payment_Gateway` lifecycle kako bi checkout ostao stabilan.
• Postback/return parametre tretirati kao nepouzdane i verificirati ih.
• Izbjeći odstupanja u zaokruživanju usklađenim iznosima s WooCommerce totalsima.
• Postavke zadržati preglednima i prijateljskima u `WooCommerce → Settings → Payments`.

Pregled rješenja

Implementirali smo WooCommerce gateway plugin koji:

• registrira novu metodu plaćanja (`paywiser`) s podesivim naslovom/opisom
• podržava dva načina: Redirect (kupac se preusmjerava na Paywiser stranicu za plaćanje) i Hosted (podaci kartice unose se u checkout UI i šalju Paywiseru).
• šalje transakcije na Paywiser TxHandler putem HTTP POST-a na `https://office.paywiser.com/secure/txHandler.php`
• prima i verificira rezultate putem postback endpointa (`/wc-api/pw-postback`) i return URL handlerja na strani `order-received` (gdje je relevantno).

Arhitektura i tehnički pristup

Konfiguracija gatewaya

• `sid` i `rcode`
• tip rješenja: `redirect` ili `hosted`
• akcija transakcije: `PREAUTH` ili `PAYMENT`

Zagon checkouta

• šalje formu na TxHandler s iznosima/valutom, podacima kupca/računa, postback URL i redirect URL
• uključuje request hash (MD5) za validaciju zahtjeva

Postback verifikacija i zaključek narudžbe

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

• uspješna plaćanja: `payment_complete(txid)` (varijante ovisno o redirect/hosted)
• neuspješna plaćanja: status `failed` s dijagnostičkim porukama

WooCommerce Blocks podrška

Plugin uključuje Blocks integraciju (`checkout.js`) i deklarira kompatibilnost s WooCommerce funkcijama (Cart/Checkout Blocks).

Tehnološki stack

• 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 i mapiranje u WooCommerce statusne tranzicije.
2. Implementacija gateway nastavitev i validacije u wp-admin.
3. Implementacija TxHandler POST pošiljanja i request hashinga.
4. Dodajanje verificiranega postback handlerja (`/wc-api/pw-postback`) i return URL verifikacije.
5. Integracija WooCommerce Blocks checkout i end-to-end testiranje obeh rješenja.

Rezultati i učinak

• WooCommerce trgovci mogu omogućiti Paywiser kartična plaćanja s predvidljivim tokom.
• podržane su redirect i hosted varijante
• server-side postbackovi se verificiraju prije promjene statusa
• checkout ostaje kompatibilan s legacy i Blocks checkout iskustvom

Refleksija

Redirect-based plaćanja operativno su sigurna samo ako je server-to-server postback izvor istine i ako je verificiran prije promjene statusa. To sprječava prakse “status po URL parametru” i smanjuje opterećenje podrške zbog dvosmislenih ishoda.

Sažetak

Plugin integrira Paywiser u WooCommerce s dva podržana načina plaćanja, verificiranim postbackom i kompatibilnošću s legacy i Blocks checkout tokovima.