> ## 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.

# POS Payment Integrations

> Initiate and verify payments using Flouci's POS devices, from your external system.

## Initiate POS Transaction

This endpoint allows a user to create and send a transaction to a POS terminal.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST 'https://developers.flouci.com/api/transactions/init_pos_transaction' \
    -H 'Authorization: Bearer <APP_PUBLIC>:<APP_SECRET>' \
    -H 'Content-Type: application/json' \
    -d '{
      "id_terminal": "terminal",
      "serial_number": "SN123456",
      "amount_in_millimes": 1000,
      "payment_method": "WALLET",
      "developer_tracking_id": "dev_track_123"
    }'
  ```
</CodeGroup>

### Body

<ParamField body="id_terminal" type="string" required>
  Unique identifier of the POS terminal.
</ParamField>

<ParamField body="serial_number" type="string" required>
  Serial number of the POS terminal.
</ParamField>

<ParamField body="amount_in_millimes" type="integer" required>
  Transaction amount in millimes.
</ParamField>

<ParamField body="payment_method" type="string" required>
  Payment method (NFC, CARD, WALLET, CHECK).
</ParamField>

<ParamField body="developer_tracking_id" type="string" required>
  An ID for you to track the payment. This is a free field that Flouci doesn't check against
</ParamField>

<ParamField body="webhook" type="string">
  Webhook URL to notify transaction status.
</ParamField>

<ResponseExample>
  ```json 201 theme={null}
  {
    "success": true,
    "terminal_id": "testing1234",
    "status_code": 201
  }
  ```
</ResponseExample>

***

## Get POS Transaction Status

This endpoint retrieves the status of a POS transaction.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET 'https://developers.flouci.com/api/transactions/get_pos_transaction_status?developer_tracking_id=dev_track_123' \
    -H 'Authorization: Bearer <APP_PUBLIC>:<APP_SECRET>'
  ```
</CodeGroup>

### Query Parameters

<ParamField query="flouci_transaction_id" type="uuid">
  Unique transaction ID from Flouci. Mutually exclusive with `developer_tracking_id`.
</ParamField>

<ParamField query="developer_tracking_id" type="string">
  An ID for you to track the payment. This is a free field that Flouci doesn't check against. May return multiple rows if you reused the same tracking ID.
</ParamField>

<ParamField query="id_terminal" type="string">
  Optional terminal identifier to narrow the lookup to a single terminal.
</ParamField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "transactions": [
      {
        "developer_tracking_id": "7cd66b29-a8b7-4e4c-aedf-0d98eeb92703",
        "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"
      }
    ],
    "status_code": 200
  }
  ```
</ResponseExample>

### Response Fields

<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 from Flouci.
</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. For POS, possible values are `PROCESSING` (auth pending), `AVAILABLE` (settled into your wallet), or `NOT_APPLICABLE` (failed / refunded). POS transactions never reach `IN_PAYOUT` or `PAID` — they settle directly into your Flouci wallet rather than entering the card payout pipeline. See [Settlement Status](/api-reference/verify-transaction#settlement-status) for the full reference.
</ResponseField>

<Note>
  In test mode, NFC mock responses do not include `settlement_status`. Production responses always include it.
</Note>