POS Transactions

POS (point of sales) transactions represent payment transactions that are initiated and driven directly on a physical terminal device. This is in contrast to transactions created purely through an API, such as a card-not-present charge.

A POS transaction is the record of a payment flow that runs through a physical terminal. The point of service, such as a diner's table, creates it and enters at the terminal what to charge. The transaction can then be polled or listed to see the resulting status and the core transaction. The typical lifecycle that includes a POS transaction:

Creating one
Use POST /v2/pos/transactions.
This initiates a transaction on a specific terminal device with predefined details. These include the amount, transaction type, such as sale or authorization, currency, customer, pricing type, and whether to wait for the terminal to accept it. The terminal handles the actual card read (readingMethod) and cardholder interaction.

Tracking status
A POS transaction has its own lifecycle status (posTransactionStatus). This is such as TransactionProcessing or Completed and is separate from the underlying core transactionId it eventually links to once processed.

Listing them
Use GET /v2/pos/transactions.
This returns a paginated list of POS transactions, filterable by terminalId, showing fields like processedAmount, transactionType, and the linked transactionId.

Operations

Lists POS transactions

Request

GET {{baseURL}}/v2/pos/transactions

This endpoint lists POS transactions.

Each item in the response contains a reduced transaction object. Fields are limited to the most relevant transaction information. This is often sufficient for rendering transaction lists, dashboards, and reconciliation views. Situations requiring full detail context, such as for decline details, AVS response, or transaction events, are available with GET /v2/pos/transactions/{{posTransactionId}}.

This endpoint requires a merchant API token. A partner API token will result in a permissions error including possibly a 403 response.

See Also:
To retrieve a POS transaction by ID, see GET /v2/pos/transactions/{posTransactionId}.
To create a new POS transaction, see POST /v2/pos/transactions.
To cancel a POS transaction, see POST /v2/pos/transactions/{posTransactionId}/cancel.
To create a POS transaction reversal, see POST /v2/pos/transactions/reversal.

Security

Bearer

Query

pageIndexinteger, (int32), >= 0

Specifies the page number of the returned search results.

A page is considered each set of the pageSize values.

The page count is zero-based. The maximum for pageIndex, or the page number, is the pageSize divided by the total count rounded down. For example, the pageSize is 50 and the total is 130. That means there are three pages, but the pageIndex value is in the inclusive range from zero to two.

Value restrictions include:

A value less than zero is not permitted.
Values equal to or greater than totalPages end successfully but will not return any items.

For page size information, see pageSize.

Example: 0

Default:0

pageSizeinteger, (int32), [ 1 .. 100 ]

Specifies the number of items for each page of the returned search results.

A page is considered each set of the pageSize values.

For page numbering information, see pageIndex.

Example: 50

Default:20

sortBystring, <= 21 characters

Specifies a field name to sort the results by.

If null or omitted, results come back newest first.

The sort order is specified by the sortOrder value.

The following fields may be used to sort results:
createdOn
posTransactionStatus

Example: createdOn

Example:sortBy=createdOn

sortOrderstring, <= 4 characters

Specifies the sort order.

The sort order is specified by the sortOrder value.
The field that gets sorted by is specified by the sortBy value.

Valid values are:

Value	Description
asc	Sorts results in ascending order, from the lowest value to the highest, or from the oldest timestamp to the most recent.
desc	Sorts results in descending order, from the highest value to the lowest, or from the most recent timestamp to the oldest.

Default:"desc"

Example:sortOrder=desc

terminalIdstring, (uuid)

Specifies a filter for terminal identifier.

Example: 57dbdbc6-fef4-44b8-816a-4372c063f1ec

Example:terminalId=57dbdbc6-fef4-44b8-816a-4372c063f1ec

fromDatestring, (date-time)

Specifies a filter to return items at or after this date-time (in an ISO 8601 date-time format).

If only fromDate is specified, the search returns all available items from the fromDate value to the present. The fields fromDate and toDate may be used together to create an inclusive range. We recommend creating an inclusive range to avoid a potentially excessive number of returns.

Example: 2025-01-27T12:05:54.322Z

Example:fromDate=2025-01-27T12:05:54.322Z

toDatestring, (date-time)

Specifies a filter to return items at or before this date-time (in an ISO 8601 date-time format).

If only toDate is specified, the search returns all available items up to the toDate value. The fields fromDate and toDate may be used together to create an inclusive range. We recommend creating an inclusive range to avoid a potentially excessive number of returns.

Example: 2026-02-27T12:05:54.322Z

Example:toDate=2026-02-27T12:05:54.322Z

posTransactionStatusstring

Specifies a filter for the POS transaction status.

Valid values are:

Value	Description
Cancelled	The POS transaction was canceled before it completed.
Completed	The POS transaction finished processing successfully.
Failed	The POS transaction did not complete because of an error.
InProgress	The POS transaction is still being processed.

Example: Completed

Enum:"InProgress""Completed""Cancelled""Failed"

Example:posTransactionStatus=Completed

curl -i -X GET \
  'https://sandbox.api.flute.com/v2/pos/transactions?pageIndex=0&pageSize=20&sortBy=createdOn&sortOrder=desc&terminalId=57dbdbc6-fef4-44b8-816a-4372c063f1ec&fromDate=2025-01-27T12%3A05%3A54.322Z&toDate=2026-02-27T12%3A05%3A54.322Z&posTransactionStatus=Completed' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Bodyapplication/json

itemsArray of objects or null

pageInfoobject

Indicates an object describing the pagination status.

If additional pages to review are needed, repeat the exact same search but include a new pageIndex value. Typically, this will increment the current pageIndex by one. However, any valid value may be used. Value restrictions include:

A value less than zero is not permitted.
Values equal to or greater than totalPages end successfully but will not return any items.

Response

{
  "items": [
    {
      "posTransactionId": "cdf3b72b-6bb5-4707-8963-1f73456323d8",
      "createdOn": "2026-06-03T21:54:31.884Z",
      "terminalId": "bcd3a843-9f21-4a71-a019-e1b336b65496",
      "posTransactionStatus": "Completed",
      "transactionId": "1782bc6c-efb0-416d-8e62-627401707177",
      "processedAmount": 135.5,
      "currencyCode": "USD"
    },
    {
      "posTransactionId": "18090b35-0758-4a5b-81ae-927d4496cd53",
      "createdOn": "2026-06-03T21:59:31.884Z",
      "terminalId": "bff9c356-fb17-4ed8-89ad-d980c92e391e",
      "posTransactionStatus": "InProgress",
      "transactionId": null,
      "processedAmount": 135.5,
      "currencyCode": "USD"
    }
  ],
  "pageInfo": {
    "pageIndex": 0,
    "pageSize": 20,
    "totalItems": 150,
    "totalPages": 8,
    "hasMore": true
  }
}