Skip to main content
Track what’s new in the Flouci Payment API. Entries are listed in reverse-chronological order.
Released October 30, 2026

Transaction History: corrected route, status values, and date rules

The Transaction History page now documents the public endpoint, GET /api/v2/history. The previous version showed an internal route (/api/developers/history), a merchant_id parameter, and raw status codes (S, AS, PF, P) that the public API does not accept.The endpoint also handles dates more predictably:
  • A plain date such as end_date=2026-05-20 now covers the whole day, so passing the same date to start_date and end_date returns that day’s transactions instead of none.
  • A date in the future now returns error 1003 with its message, instead of a generic validation error.
operation_status now matches the status reported in each row. FAILURE includes wallet and mobile-switch failures, PENDING no longer returns expired sessions, and REFUNDED works for POS transactions. EXPIRED and CANCELED with type=pos return error 1005 instead of an empty list.The page also documents pagination (page, page_size) and time zones (input in Tunis time, created_at and paid_at in UTC).
Results change for some filters: a plain-date end_date now returns the rest of that day, and operation_status returns the rows whose reported status matches it. If you worked around the previous filter behaviour, review those queries.
Released October 2026

Signed payment webhooks and JSON payment events

Payment webhooks now carry an X-Flouci-Signature header, an HMAC-SHA256 computed with your app’s private token, so you can check that a call comes from Flouci before acting on it. The default GET <webhook>?payment_id=<id>&success=<True|False> call is unchanged apart from the new header.A new optional webhook_version field on Generate Payment lets you receive a signed JSON POST instead, with a payment.succeeded or payment.failed event in the same format as subscription webhooks.See Payment Webhooks for both formats, the verification code and how to migrate.
Additive and backward compatible. Existing webhook handlers keep working; add the signature check to reject forged calls.
Released August 17, 2026

Card payment error codes are now documented

The Error Dictionary lists the 37 card payment error codes observed in production, with the verbatim message returned by the card processing platform, what each code means, and the action to offer your customer.Codes are also grouped into handling patterns so you can implement one behavior per pattern instead of a branch per code — including the two cases that need care: never retry -2013 or -2007 on the same order, and always verify the final state of the order after 100801 before offering a retry, to avoid a double debit.
Documentation only — no API behavior changed. These codes were already returned by the platform.
Released May 28, 2026

Settlement status on Verify and History responses

Every transaction returned by the Verify Payment, POS Get Transaction Status, and Transaction History endpoints now carries a settlement_status field describing where the funds sit between the moment of payment and the moment they reach your bank account.The field is one of five values:
  • PROCESSING — succeeded card payment inside the T+1 settlement window
  • AVAILABLE — eligible for inclusion in the next payout
  • IN_PAYOUT — committed to a payout request, wire not yet sent
  • PAID — wired to your bank account (terminal state)
  • NOT_APPLICABLE — outside the settlement lifecycle (failed, refunded, pending, etc.)
See the full reference in Settlement Status.
This change is additive and backward compatible — existing status and payment_status fields are unchanged. Clients that ignore settlement_status see no behavior change.

New Transaction History endpoint

The Transaction History endpoint is now documented with full query-parameter, response, and filtering reference for both branches:
  • type=online — card, wallet, and mobile-switch payments
  • type=pos — POS terminal transactions
Filters: date range, payment status (operation_status), app_token (online only), and terminal_id (POS only).