Fliqa

Context

Fliqa biedt een betaalproduct waarmee klanten via hun gekozen bank kunnen betalen (PIS / open banking-flow). Voor WooCommerce-verkopers vereiste dit een gatewayplugin die past in de orderlifecycle van WooCommerce en rekening houdt met redirects, callbacks en asynchrone finalisatie van betalingen.

Probleem

WooCommerce-checkout heeft duidelijke verwachtingen:

• Het verwacht voorspelbare betaalstatus-overgangen (pending → on-hold/paid/failed).
• Het vereist duidelijke afhandeling van “klant keert terug”-scenario’s (success, cancel, close).
• Het vereist veilige opslag van configuratie en een beheer-UX onder `WooCommerce → Settings → Payments`.

De integratie moest ook edge cases uit de praktijk afhandelen (afgebroken checkout, betaalfouten, dubbele submits) zonder inconsistente orderstatussen te creëren.

Projectdoelen

• Fliqa aanbieden als volwaardige betaalmethode in WooCommerce-checkout (legacy + Blocks).
• Orderstatus consistent houden, ook als de klant tijdens betaling de site verlaat.
• Een duidelijke configuratie in wp-admin aanbieden.
• Zowel sandbox- als productieomgevingen ondersteunen.

Beperkingen & Uitdagingen

• De `WC_Payment_Gateway`-lifecycle volgen zodat checkoutgedrag voorspelbaar blijft.
• Secrets server-side houden (API key/secret; webhook secret) en niet lekken naar de frontend.
• Webhook-authenticiteit verifiëren (signature-validatie, ondersteuning voor secret-rotatie).
• Betalingsfinalisatie robuust maken, ook als de klant niet terugkeert (webhook + reconciliatie).

Oplossingsoverzicht

We hebben een WooCommerce-gatewayplugin geïmplementeerd die:

• Registreert een nieuwe betaalmethode (`fliqa`, met configureerbare titel/omschrijving).
• Laadt de Fliqa SDK (`https://assets.fliqa.io/sdk/latest/fliqaComponent.js`) en opent de betaal-dialoog/iframe.
• Voegt ordermetadata toe aan het betaalverzoek (order id/key, customer id/email indien beschikbaar).
• Finaliseert orders via een geverifieerd webhook-endpoint (`/wc-api/fq-postback`) en een fallback reconciliatiejob voor “on-hold”-orders.
• Slaat `paymentId` op bij de order (`_fq_paymentId`) voor reconciliatie en supportworkflows.

Architectuur & Technische aanpak

De plugin volgt de standaard WooCommerce gateway-flow:

• Gatewayconfiguratie (verplicht): environment, tenant slug, point of sale (ID), API key/secret, webhook secret.
• Checkout: `process_payment()` maakt de order aan en redirect naar de betalingspagina, waar de SDK-dialoog wordt uitgevoerd met bedrag, valuta en metadata.
• Terugkeer klant: op `order-received` haalt de plugin, als `paymentId` aanwezig is, de betaalstatus op en map die naar WooCommerce-states:
• `successful` → `payment_complete(paymentId)`
• `pending` / `expired` → `on-hold` (“Wacht op Fliqa-betaling”)
• `rejected` / `canceled` / `failed` → `failed`
• Webhook: `/wc-api/fq-postback` valideert `X-Fliqa-Signature` (HMAC) tegen het geconfigureerde secret (en het vorige secret voor rotatie) en werkt daarna de orderstatus bij met dezelfde mappingregels.
• Reconciliatie: een geplande job controleert “on-hold” Fliqa-orders met `_fq_paymentId` en finaliseert ze door de payment status API aan te roepen.

De implementatie bevat WooCommerce feature-compatibility declarations (incl. Blocks checkout en custom order tables).

Technologiestack

• WordPress
• WooCommerce
• PHP (gateway implementation + webhook signature verification)
• JavaScript (WooCommerce Blocks integration + SDK execution)
• Fliqa payment API + webhooks

Implementatieproces

1. Het statemodel definiëren en het autoritatieve completion pad bepalen (webhook-first).
2. Gateway-instellingen en validatie in wp-admin implementeren.
3. SDK-executie integreren en deterministische ordermetadata doorgeven.
4. Webhook-afhandeling met signature-verificatie implementeren, met ondersteuning voor secret-rotatie.
5. Reconciliatie toevoegen voor on-hold orders en end-to-end flows testen (sandbox → productie).

Resultaten en impact

• WooCommerce-verkopers kunnen een bankbetaalmethode activeren zonder custom checkout rewrites.
• Betalingsfinalisatie is deterministisch: de webhook werkt orders bij, ook als de klant de return flow afbreekt.
• Operations krijgt een stabiele referentie (`paymentId`) op de order voor support en reconciliatie.

Reflectie

De belangrijkste ontwerpkeuze was om betaalcompletion standaard als asynchroon te behandelen en het webhook-pad als autoritatief te maken, met reconciliatie als vangnet. Dit voorkomt “vastgelopen” orders en vermindert handmatige interventie.

Samenvatting

Deze plugin integreert Fliqa als een WooCommerce payment gateway op productieniveau, met geverifieerde webhooks, duidelijke state-mapping en compatibiliteit met zowel legacy- als Blocks checkout flows.