POS / Terminal Integration

Flute's terminal integration connects your POS application to a Flute terminal for in-person card payments. Your POS application sends transaction requests to the Flute API, which routes them to the terminal for card interaction (tap, insert, swipe). The terminal reads the card data and sends it to Flute, which submits the payment to the card processor.

1. Your POS application creates a transaction through the API, specifying the terminal and amount.
2. Flute sends the transaction to the terminal.
3. The terminal prompts the customer to present their card.
4. The terminal reads the card data and sends it to Flute.
5. Flute submits the payment to the card processor and stores the result.
6. Your POS application retrieves the result by polling the API.

All API requests use the following base URLs. Use the sandbox environment during development and testing, and switch to production when you are ready to go live.

Sandbox Environment:

https://sandbox.api.flute.com/pos-api/v1

Production Environment:

https://api.flute.com/pos-api/v1

Before processing transactions, you need to know which terminals are available.

To list the available terminals, use:
GET /pos-api/v1/terminals

This returns a paginated list of terminals assigned to your merchant account.

Each terminal in the response includes:

\

To display the status of a specified terminal, use:
GET /pos-api/v1/terminals/{terminalId}/status

This returns detailed real-time status for that terminal.

\

The following are individual steps or endpoints used in the POS transaction workflow.

The following topics are available:

• Starting a POS Transaction
• Payment Method Storage
• Retrieving POS Transactions
• Retrieving a Specified POS Transaction
• Printing a POS Transaction Receipt
• Canceling a POS Transaction

To start a new POS transaction, use:
POST /pos-api/v1/pos-transactions

The following are the request parameters.

Example — Sale transaction:

curl -X POST 'https://sandbox.api.flute.com/pos-api/v1/pos-transactions' \
  -H 'Authorization: Bearer API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "terminalId": "d4e5f6a7-b8c9-0123-4567-89abcdef0123",
    "transactionTypeId": 2,
    "amount": 25.99,
    "posDeviceId": "POS-REGISTER-01",
    "referenceId": "ORDER-4521",
    "waitForAcceptanceByTerminal": false
  }'

Response:

{
  "posTransactionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "statusId": 1,
  "status": "TerminalConnecting"
}

When requestPaymentMethodStorageConsent is set to true, the terminal displays a consent prompt after the transaction is approved. This asks the customer if they want to save their payment method for future use (such as one-off payments, future orders, or recurring charges).

A customerId must be provided in the request to use this feature. Without it, the consent prompt will not be shown. If the card is already saved under the provided customer record, the terminal skips the prompt automatically.

If the customer consents, the payment method is saved to the customer record. If the customer declines, the transaction is unaffected and no payment method is stored.

To retrieve the stored payment method, call one of the following from the backend after the transaction completes:

• GET /pay-api/v1/customers/{customerId}
• GET /pay-api/v1/customers/{customerId}/payment-methods

To retrieve POS transactions, use:
GET /pos-api/v1/pos-transactions

Specified terminals may be listed by filtering with the terminalId.

This returns a paginated list of POS transactions.

To retrieve a specified POS transaction, use:
GET /pos-api/v1/pos-transactions/{posTransactionId}

The following are the input parameters.

When the transaction completes (isCompleted: true), the response includes full transaction details in the transaction object:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "posTransactionStatusId": 6,
  "posTransactionStatus": "Completed",
  "isCompleted": true,
  "amount": 25.99,
  "transaction": {
    "transactionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "amount": 25.99,
    "transactionStatus": "Captured",
    "authCode": "A12345"
  }
}

You can cancel a transaction that hasn't completed yet. To cancel a specified POS transaction, use:
POST /pos-api/v1/pos-transactions/{posTransactionId}/cancel

This returns the updated transaction status. Cancellation is only possible while the transaction is in a non-final state, such as TerminalConnecting or TransactionProcessing.

To print a receipt on a terminal for a completed transaction, use:
POST /pos-api/v1/pos-transactions/{posTransactionId}/print

The following is an example request

{
  "posTransactionId": "d4e5f6a7-b8c9-0123-4567-89abcdef0123"
}

If successful, this returns a 200 OK with no response body and will print the receipt

After creating a transaction, poll the GET endpoint to track its progress.

Polling when creating a transaction:

• Short polling: Set waitForAcceptanceByTerminal: false when creating the POS transaction. Your POS controls the polling interval to retrieve the transaction status.
• Long polling: Set waitForAcceptanceByTerminal: true when creating the POS transaction. The response holds until the transaction is accepted by the terminal device or times out, reducing the number of API calls.

Polling to get the transaction results:

• Short polling: Poll GET with waitForTransactionProcessing: false when you want to check the transaction status at your own interval.
• Long polling: Poll GET with waitForTransactionProcessing: true to hold the request until the transaction reaches a final status, reducing the number of API calls.

Check the isCompleted field to determine if the transaction has reached a final status.

All endpoints return standard HTTP status codes: