Fliqa

Context

Fliqa provides a payment product that enables customers to pay through their chosen bank (PIS / open banking flow). For WooCommerce merchants, this required a gateway plugin that fits WooCommerce’s order lifecycle and supports the operational reality of redirects, callbacks and asynchronous payment finalization.

Problem

WooCommerce checkout is opinionated:

• It expects predictable payment state transitions (pending → on-hold/paid/failed).
• It needs clear handling of “customer returned” scenarios (success, cancel, close).
• It requires safe configuration storage and admin UX under `WooCommerce → Settings → Payments`.

The integration also had to handle real-world edge cases (abandoned checkout, payment failures, double submissions) without creating inconsistent order states.

Project Goals

• Offer Fliqa as a first-class payment method in WooCommerce checkout (legacy + Blocks).
• Keep the order state consistent even when the customer leaves the site during payment.
• Provide a clear configuration surface in wp-admin.
• Support both sandbox and production environments.

Constraints & Challenges

• Follow the `WC_Payment_Gateway` lifecycle to keep checkout behavior predictable.
• Keep secrets server-side (API key/secret; webhook secret) and avoid leaking them into frontend.
• Verify webhook authenticity (signature validation, secret rotation support).
• Make payment finalization robust even if the customer does not return (webhook + reconciliation).

Solution Overview

We implemented a WooCommerce gateway plugin that:

• Registers a new payment method (`fliqa`, configurable title/description).
• Loads the Fliqa SDK (`https://assets.fliqa.io/sdk/latest/fliqaComponent.js`) and opens the payment dialog/iframe.
• Includes order metadata in the payment request (order id/key, customer id/email when available).
• Finalizes orders via a verified webhook endpoint (`/wc-api/fq-postback`) and a fallback reconciliation job for “on-hold” orders.
• Stores `paymentId` on the order (`_fq_paymentId`) for reconciliation and merchant support workflows.

Architecture & Technical Approach

The plugin follows the standard WooCommerce gateway flow:

• Gateway configuration (required): environment, tenant slug, point of sale (ID), API key/secret, webhook secret.
• Checkout: `process_payment()` creates the order and redirects to the payment receipt page, where the SDK dialog is executed with amount, currency and metadata.
• Customer return: on `order-received`, if `paymentId` is present, the plugin fetches payment status and maps it into WooCommerce states:
• `successful` → `payment_complete(paymentId)`
• `pending` / `expired` → `on-hold` (“Awaiting Fliqa payment”)
• `rejected` / `canceled` / `failed` → `failed`
• Webhook: `/wc-api/fq-postback` validates `X-Fliqa-Signature` (HMAC) against the configured secret (and previous secret for rotation), then updates the order status using the same mapping rules.
• Reconciliation: a scheduled job checks “on-hold” Fliqa orders with `_fq_paymentId` and finalizes them by calling the payment status API.

The implementation includes WooCommerce feature compatibility declarations (including Blocks checkout and custom order tables).

Technology Stack

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

Implementation Process

1. Define the state model and the authoritative completion path (webhook-first).
2. Implement the gateway settings and validation in wp-admin.
3. Integrate the SDK execution and pass deterministic order metadata.
4. Implement signature-verified webhook handling with secret rotation support.
5. Add reconciliation for on-hold orders and test end-to-end flows (sandbox → production).

Results & Impact

• WooCommerce merchants can enable a bank payment method without custom checkout rewrites.
• Payment finalization is deterministic: webhook updates orders even if the customer abandons the return flow.
• Operations teams get a stable reference (`paymentId`) stored on the order for support and reconciliation.

Reflection

The most important design choice was to treat payment completion as asynchronous by default and to make the webhook path authoritative, with reconciliation as a safety net. This prevents “stuck” orders and reduces manual intervention.

Summary

This plugin integrates Fliqa as a production-grade WooCommerce payment gateway with verified webhooks, clear state mapping, and compatibility across both legacy and Blocks checkout flows.