Fliqa.IO

Kontekst

Fliqa ponuja plačilni produkt, ki kupcem omogoča plačilo prek izbrane banke (PIS / open banking tok). Za WooCommerce trgovce je bila potrebna gateway integracija, ki sledi WooCommerce življenjskemu ciklu naročil ter podpira realnost preusmeritev, povratnih klicev in asinhrone finalizacije plačil.

Problem

WooCommerce checkout je izrazito “opinionated”:

• pričakuje predvidljive prehode stanj (pending → on-hold/paid/failed)
• zahteva jasno obravnavo “customer returned” scenarijev (success, cancel, close)
• potrebuje varno shranjevanje nastavitev in admin UX pod `WooCommerce → Settings → Payments`

Integracija je morala obvladati realne edge case (abandoned checkout, payment failure, dvojne oddaje) brez ustvarjanja nekonsistentnih stanj naročil.

Cilji projekta

• Ponuditi Fliqa kot prvovrstno plačilno metodo v WooCommerce checkoutu (legacy + Blocks).
• Ohraniti konsistentno stanje naročila tudi, ko kupec zapusti spletno mesto med plačilom.
• Zagotoviti jasen konfiguracijski vmesnik v wp-admin.
• Podpreti okolja sandbox in production.

Omejitve in izzivi

• Slediti `WC_Payment_Gateway` lifecycle, da je checkout predvidljiv.
• Ohraniti skrivnosti strežniško (API key/secret; webhook secret) in jih ne izpostaviti v frontend.
• Verificirati webhook avtentičnost (signature validation, podpora rotaciji skrivnosti).
• Finalizacija mora delovati tudi, če se kupec ne vrne (webhook + poravnava).

Pregled rešitve

Implementirali smo WooCommerce gateway plugin, ki:

• registrira novo plačilno metodo (`fliqa`, z nastavljivim naslovom/opisom)
• naloži Fliqa SDK (`https://assets.fliqa.io/sdk/latest/fliqaComponent.js`) in odpre plačilni dialog/iframe
• vključi metapodatke naročila v plačilno zahtevo (order id/key, customer id/email)
• finalizira naročila prek verificiranega webhook endpointa (`/wc-api/fq-postback`) in fallback poravnave za “on-hold” naročila
• shrani `paymentId` na naročilu (`_fq_paymentId`) za poravnavo in podporne procese

Arhitektura in tehnični pristop

Plugin sledi standardnemu WooCommerce gateway toku:

• Konfiguracija: okolje, tenant slug, POS (ID), API key/secret, webhook secret.
• Checkout: `process_payment()` ustvari naročilo in preusmeri na payment receipt, kjer SDK izvede dialog z zneskom, valuto in metapodatki.
• Customer return: na `order-received` plugin prebere status plačila in ga preslika v WooCommerce stanja:
• `successful` → `payment_complete(paymentId)`
• `pending` / `expired` → `on-hold` (“Awaiting Fliqa payment”)
• `rejected` / `canceled` / `failed` → `failed`
• Webhook: `/wc-api/fq-postback` validira `X-Fliqa-Signature` (HMAC) s konfiguriranim secretom (in prejšnjim secretom za rotacijo), nato posodobi status naročila po istih pravilih.
• Poravnava: scheduled job preveri “on-hold” Fliqa naročila z `_fq_paymentId` in jih zaključi z API-jem.

Implementacija vključuje deklaracije kompatibilnosti za WooCommerce features (vključno z Blocks checkout in custom order tables).

Tehnološki sklad

• WordPress
• WooCommerce
• PHP (gateway implementacija + webhook signature verifikacija)
• JavaScript (WooCommerce Blocks integracija + SDK izvršitev)
• Fliqa payment API + webhooks

Proces implementacije

1. Definicija modela stanj in avtoritativne poti zaključka (webhook-first).
2. Implementacija gateway nastavitev in validacij v wp-admin.
3. Integracija SDK izvršitve in pošiljanje determinističnih metapodatkov naročila.
4. Implementacija signature-verified webhook handlerja z podporo za rotacijo skrivnosti.
5. Dodatek poravnave “on-hold” naročil in end-to-end testiranje (sandbox → production).

Rezultati in učinek

• asinhroni izidi (webhook-driven)
• tok povratka kupca (poizvedba + preslikava statusa)
• operativna poravnava za naročila, ki ostanejo on-hold

Refleksija

Najpomembnejša odločitev je bila obravnavati zaključek plačila kot asinhron proces in narediti webhook pot avtoritativno, z poravnavo kot varnostno mrežo. To prepreči “zastala” naročila in zmanjšuje ročne intervencije.

Povzetek

Plugin integrira Fliqa kot produkcijsko WooCommerce payment gateway rešitev z verificiranimi webhooks, jasnimi preslikavami stanj in kompatibilnostjo za legacy in Blocks checkout tokove.