Fliqa.IO

Kontekst

Fliqa nudi proizvod plaćanja koji kupcima omogućuje plaćanje putem odabrane banke (PIS / open banking tok). Za WooCommerce trgovce bila je potrebna gateway integracija koja slijedi WooCommerce životni ciklus narudžbi te podržava realnost preusmjeravanja, povratnih poziva i asinkrone finalizacije plaćanja.

Problem

WooCommerce checkout je izrazito “opinionated”:

• očekuje predvidljive prijelaze statusa (pending → on-hold/paid/failed)
• zahtijeva jasnu obradu “customer returned” scenarija (success, cancel, close)
• traži sigurno spremanje postavki i admin UX pod `WooCommerce → Settings → Payments`

Integracija je morala pokriti realne edge-caseove (abandoned checkout, payment failure, dvostruke predaje) bez stvaranja nekonzistentnih statusa narudžbi.

Ciljevi projekta

• Ponuditi Fliqa kao prvoklasnu metodu plaćanja u WooCommerce checkoutu (legacy + Blocks).
• Očuvati konzistentan status narudžbe čak i kada kupac napusti web-stranicu tijekom plaćanja.
• Osigurati jasan konfiguracijski UI u wp-adminu.
• Podržati sandbox i production okruženja.

Ograničenja i izazovi

• Slijediti `WC_Payment_Gateway` lifecycle kako bi checkout bio predvidljiv.
• Čuvati tajne na serveru (API key/secret; webhook secret) i ne izlagati ih frontendu.
• Verificirati autentičnost webhooka (signature validation, podrška rotaciji tajni).
• Finalizacija mora raditi i ako se kupac ne vrati (webhook + usklađivanje).

Pregled rješenja

Implementirali smo WooCommerce gateway plugin koji:

• registrira novu metodu plaćanja (`fliqa`) s podesivim naslovom/opisom
• učitava Fliqa SDK (`https://assets.fliqa.io/sdk/latest/fliqaComponent.js`) i otvara dijalog/iframe za plaćanje
• uključuje metapodatke narudžbe u zahtjev za plaćanje (order id/key, customer id/email)
• finalizira narudžbe preko verificiranog webhook endpointa (`/wc-api/fq-postback`) i fallback usklađivanja za “on-hold” narudžbe
• sprema `paymentId` na narudžbi (`_fq_paymentId`) za usklađivanje i support procese

Arhitektura i tehnički pristup

Plugin slijedi standardni WooCommerce gateway tok:

• Konfiguracija: okruženje, tenant slug, POS (ID), API key/secret, webhook secret.
• Checkout: `process_payment()` stvara narudžbu i preusmjerava na payment receipt, gdje SDK otvara dijalog s iznosom, valutom i metapodacima.
• Customer return: na `order-received` plugin čita status plaćanja i preslikava ga u WooCommerce statuse:
• `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 (i prethodnim secretom za rotaciju), zatim ažurira status narudžbe po istim pravilima.
• Usklađivanje: scheduled job provjerava “on-hold” Fliqa narudžbe s `_fq_paymentId` i zatvara ih putem API-ja.

Implementacija uključuje deklaracije kompatibilnosti za WooCommerce značajke (uključujući Blocks checkout i custom order tables).

Tehnološki stack

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

Proces implementacije

1. Definicija modela statusa i autoritativnog toka finalizacije (webhook-first).
2. Implementacija gateway postavki i validacija u wp-adminu.
3. Integracija izvršavanja SDK-a i slanje determinističnih metapodataka narudžbe.
4. Implementacija signature-verified webhook handlera uz podršku za rotaciju tajni.
5. Dodavanje usklađivanja “on-hold” narudžbi i end-to-end testiranje (sandbox → production).

Rezultati i učinak

• asinhroni izidi (webhook-driven)
• tok povratka kupca (poizvedba + preslikava statusa)
• operativno usklađivanje za narudžbe koje ostanu on-hold

Refleksija

Najvažnija odluka bila je tretirati završetak plaćanja kao asinkron proces i postaviti webhook kao autoritativni put, uz usklađivanje kao sigurnosnu mrežu. To sprječava “zaglavljene” narudžbe i smanjuje ručne intervencije.

Sažetak

Plugin integrira Fliqa kao produkcijsko WooCommerce payment gateway rješenje s verificiranim webhookovima, jasnim preslikavanjima statusa i kompatibilnošću za legacy i Blocks checkout tokove.