Skip to main content
The Transaction History endpoint returns a paginated list of your transactions, with optional filters for date range, payment status, app token, and terminal. Results are scoped to the merchant that owns the app credentials in the Authorization header — you don’t pass a merchant identifier. Each row includes a settlement_status field indicating where the transaction sits in the settlement lifecycle. The endpoint has two branches selected by the type query parameter:
  • type=online (default) — returns card, wallet, and mobile-switch payments created through the online payment API.
  • type=pos — returns transactions processed by a POS terminal.

Query Parameters

string
default:"online"
Which branch of the history to query. Either online (returns online payments — card, wallet, mobile switch) or pos (returns POS terminal transactions).
datetime
ISO-8601 datetime or date. Inclusive lower bound on the transaction creation time. A plain date (2026-05-20) means 00:00 that day. Unbounded if omitted. Cannot be in the future. See Dates and time zones.
datetime
ISO-8601 datetime or date. Inclusive upper bound on the transaction creation time. A plain date (2026-05-26) covers the whole day, up to 23:59:59.999999. Must be ≥ start_date and cannot be in the future. See Dates and time zones.
string
Optional status filter. One of SUCCESS, PENDING, FAILURE, EXPIRED, PREAUTH_SUCCESS, REFUNDED, or CANCELED — see the table below for what each value matches on each branch. Any other value returns a 400.
uuid
Online only. Filter results to a specific app token recorded on the payment payload.
string
POS only. Restrict results to a single terminal. Maximum 16 characters. Returns a 1004 validation error if combined with type=online.
integer
default:"1"
Page number, starting at 1.
integer
Number of results per page, from 1 to 100.

operation_status accepted values

operation_status matches the status reported in the response — status for online payments, payment_status for POS transactions.
Refunded and canceled online payments are currently reported with status SYSTEM_FAILURE. Filter on REFUNDED or CANCELED to retrieve them.

Dates and time zones

  • Input. start_date and end_date accept ISO-8601 datetimes with or without an offset (2026-05-20T08:00:00Z, 2026-05-20T09:00:00+01:00, 2026-05-20T09:00:00). A value without an offset is read as Tunis time (Africa/Tunis, UTC+1).
  • Plain dates. A date without a time (2026-05-20) is also read in Tunis time: 00:00 for start_date, and the whole day for end_date. To fetch a single day, pass the same date to both: start_date=2026-05-20&end_date=2026-05-20.
  • Future dates. A start_date or end_date later than the current time returns a 1003 error. A plain end_date of today is accepted and stops at the current time.
  • Output. created_at and paid_at in the response are ISO-8601 datetimes in UTC (2026-05-20T07:00:00+00:00). Convert them to Tunis time before grouping transactions by business day.

Validation errors

Invalid queries return HTTP 400. Errors on the date, terminal, and status rules carry a numeric code:
400 response
An invalid parameter value — for example an unknown operation_status — returns the field name with the reason instead:
400 response

Response

The endpoint returns a paginated envelope. Follow next until it is null to read every page.
integer
required
Total number of transactions matching the filters, across all pages.
string
URL of the next page, or null on the last page.
string
URL of the previous page, or null on the first page.
array
required
The transactions on this page, newest first. Each element is shaped according to the requested type, as described below.
string
required
Payment method used. One of card, flouci (wallet), mpayment (mobile switch), or NA.
integer
required
Amount in millimes.
string
required
Payment status. One of SUCCESS, PENDING, EXPIRED, FAILURE, PREAUTH_SUCCESS, or SYSTEM_FAILURE.
object
Buyer information. Shape depends on the payment type.
string
Your merchant-supplied reference. May be null.
string
Only on charges of a recurring subscription. The subscription this payment belongs to — see Recurring Payments. Absent on one-off payments.
string
Only on charges of a recurring subscription. subscription_create, subscription_cycle or subscription_retry.
integer
Per-transaction fee in millimes. Returns an empty string "" until the fee has been computed.
integer
VAT in millimes. Returns an empty string "" until computed.
string
When the payment was initiated. ISO-8601 datetime in UTC.
string
When the payment was completed. ISO-8601 datetime in UTC. null if the payment has not completed.
string
required
Settlement lifecycle state for this transaction. See Settlement Status.

Examples

There is currently no query parameter to filter by settlement_status. To separate transactions by settlement state — for example, to identify what has already been wired to your bank versus what is still in flight — filter the returned list client-side on the settlement_status field.