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-20now covers the whole day, so passing the same date tostart_dateandend_datereturns that day’s transactions instead of none. - A date in the future now returns error
1003with 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).Signed payment webhooks and JSON payment events
Payment webhooks now carry anX-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.
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.
Settlement status on Verify and History responses
Every transaction returned by the Verify Payment, POS Get Transaction Status, and Transaction History endpoints now carries asettlement_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 windowAVAILABLE— eligible for inclusion in the next payoutIN_PAYOUT— committed to a payout request, wire not yet sentPAID— wired to your bank account (terminal state)NOT_APPLICABLE— outside the settlement lifecycle (failed, refunded, pending, etc.)
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 paymentstype=pos— POS terminal transactions
operation_status), app_token (online only), and terminal_id (POS only).