> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flouci.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Transaction History

> Query your online and POS transaction history with filters for date range, status, terminal, and app token.

The Transaction History endpoint returns a paginated list of your transactions, with optional filters for date range, payment status, app token, and terminal. 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.

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET 'https://developers.flouci.com/api/developers/history?merchant_id=42&type=online&start_date=2026-05-20T00:00:00' \
    -H 'Authorization: Bearer <APP_PUBLIC>:<APP_SECRET>'
  ```
</RequestExample>

## Query Parameters

<ParamField query="merchant_id" type="integer" required>
  Identifier of the merchant whose history to query. The merchant must have developer API access enabled.
</ParamField>

<ParamField query="type" type="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).
</ParamField>

<ParamField query="start_date" type="datetime">
  ISO-8601 datetime. Inclusive lower bound on the transaction creation time. Unbounded if omitted.
</ParamField>

<ParamField query="end_date" type="datetime">
  ISO-8601 datetime. Inclusive upper bound on the transaction creation time. Must be ≥ `start_date` and cannot be in the future.
</ParamField>

<ParamField query="operation_status" type="string">
  Optional status filter. Accepts the codes in the table below for both branches — POS queries map them internally to POS payment statuses.
</ParamField>

<ParamField query="app_token" type="uuid">
  **Online only.** Filter results to a specific app token recorded on the payment payload.
</ParamField>

<ParamField query="terminal_id" type="string">
  **POS only.** Restrict results to a single terminal. Maximum 16 characters. Returns a `1004` validation error if combined with `type=online`.
</ParamField>

### `operation_status` accepted values

The endpoint accepts the same status codes regardless of `type`. For POS queries the code is mapped internally.

| Code                   | Online (`type=online`)                                    | POS (`type=pos`)            |
| ---------------------- | --------------------------------------------------------- | --------------------------- |
| `S` (Success)          | matches `Success`                                         | matches `PAYMENT_SUCCEEDED` |
| `AS` (All success)     | matches `Success`, `FlouciSuccess`, `MobileSwitchSuccess` | matches `PAYMENT_SUCCEEDED` |
| `PF` (Payment failure) | matches `PaymentFailure`                                  | matches `PAYMENT_FAILED`    |
| `P` (Pending)          | matches `Pending`                                         | matches `PAYMENT_PENDING`   |

Other status codes are passed through verbatim with no automatic mapping.

### Validation errors

| Code   | Reason                                              |
| ------ | --------------------------------------------------- |
| `1002` | `start_date` is later than `end_date`.              |
| `1003` | `start_date` or `end_date` is in the future.        |
| `1004` | `terminal_id` supplied together with `type=online`. |

## Response

The endpoint returns a paginated list. Each element is shaped according to the requested `type`.

<Tabs>
  <Tab title="Online (type=online)">
    ```json theme={null}
    {
      "type": "card",
      "amount": 100000,
      "status": "SUCCESS",
      "details": {
        "name": "FOULEN BEN FOULEN",
        "approval_code": "182848"
      },
      "developer_tracking_id": "order_98231",
      "fee": 5000,
      "tva": 950,
      "settlement_status": "AVAILABLE"
    }
    ```

    <ResponseField name="type" type="string" required>
      Payment method used. One of `card`, `flouci` (wallet), `mpayment` (mobile switch), or `NA`.
    </ResponseField>

    <ResponseField name="amount" type="integer" required>
      Amount in millimes.
    </ResponseField>

    <ResponseField name="status" type="string" required>
      Payment status. One of `SUCCESS`, `PENDING`, `EXPIRED`, `FAILURE`, `PREAUTH_SUCCESS`, or `SYSTEM_FAILURE`.
    </ResponseField>

    <ResponseField name="details" type="object">
      Buyer information. Shape depends on the payment `type`.
    </ResponseField>

    <ResponseField name="developer_tracking_id" type="string">
      Your merchant-supplied reference. May be `null`.
    </ResponseField>

    <ResponseField name="fee" type="integer">
      Per-transaction fee in millimes. Returns an empty string `""` until the fee has been computed.
    </ResponseField>

    <ResponseField name="tva" type="integer">
      VAT in millimes. Returns an empty string `""` until computed.
    </ResponseField>

    <ResponseField name="settlement_status" type="string" required>
      Settlement lifecycle state for this transaction. See [Settlement Status](/api-reference/verify-transaction#settlement-status).
    </ResponseField>
  </Tab>

  <Tab title="POS (type=pos)">
    ```json theme={null}
    {
      "developer_tracking_id": "order_98231",
      "flouci_transaction_id": "1b7b29df-6826-4b33-b5a6-fb86fcc15e5c",
      "payment_status": "PS",
      "payment_method": "card",
      "amount_in_millimes": 50000,
      "currency": "TND",
      "terminal_id": "T001",
      "settlement_status": "AVAILABLE"
    }
    ```

    <ResponseField name="developer_tracking_id" type="string">
      Your merchant-supplied reference. May be `null`.
    </ResponseField>

    <ResponseField name="flouci_transaction_id" type="string" required>
      Unique POS transaction identifier.
    </ResponseField>

    <ResponseField name="payment_status" type="string" required>
      POS payment status code: `PS` (succeeded), `PP` (pending), `PF` (failed), `PR` (refunded), `RP` (refund pending), `RF` (refund failed), `PU` (unknown), `PA` (authorized).
    </ResponseField>

    <ResponseField name="payment_method" type="string" required>
      One of `card`, `wallet`, `nfc`, `check`, or `cash`.
    </ResponseField>

    <ResponseField name="amount_in_millimes" type="integer" required>
      Transaction amount in millimes.
    </ResponseField>

    <ResponseField name="currency" type="string" required>
      Currency code. Currently always `TND`.
    </ResponseField>

    <ResponseField name="terminal_id" type="string">
      Identifier of the terminal that processed the transaction. May be `null`.
    </ResponseField>

    <ResponseField name="settlement_status" type="string" required>
      Settlement lifecycle state for this transaction. POS values are limited to `PROCESSING`, `AVAILABLE`, and `NOT_APPLICABLE`. See [Settlement Status](/api-reference/verify-transaction#settlement-status).
    </ResponseField>
  </Tab>
</Tabs>

## Examples

<CodeGroup>
  ```bash Last week of online payments theme={null}
  curl -X GET 'https://developers.flouci.com/api/developers/history?merchant_id=42&type=online&start_date=2026-05-20T00:00:00' \
    -H 'Authorization: Bearer <APP_PUBLIC>:<APP_SECRET>'
  ```

  ```bash Successful POS payments on one terminal theme={null}
  curl -X GET 'https://developers.flouci.com/api/developers/history?merchant_id=42&type=pos&terminal_id=T001&operation_status=S' \
    -H 'Authorization: Bearer <APP_PUBLIC>:<APP_SECRET>'
  ```

  ```bash Online card payments by app token theme={null}
  curl -X GET 'https://developers.flouci.com/api/developers/history?merchant_id=42&type=online&app_token=602e300d-bee8-49a6-b5b7-438912669a27' \
    -H 'Authorization: Bearer <APP_PUBLIC>:<APP_SECRET>'
  ```
</CodeGroup>

<Warning>
  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.
</Warning>