Creates a POS transaction

Request

POST {{baseURL}}/v2/pos/transactions

This endpoint creates a new card present payment transaction on a semi-Integrated terminal. A semi-integrated terminal is one that is connected to a POS system, typically through a network or cable.

When called, the gateway connects to the specified terminal and starts the payment flow. This includes screens for:

Card type selection
Tip entry
Card reading, such as for tap, insert, or swipe, depending on the merchant's settings.

The terminal flow is asynchronous. Use GET /pos/transactions/{{posTransactionId}} until posTransactionStatus reaches a terminal state, such as Completed, Failed, or Cancelled. When it is Completed, check the linked transaction for the payment outcome, which may have been declined.

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

Security

Bearer

Bodyapplication/json

posDeviceIdstring or null, [ 1 .. 36 ] charactersrequired

Specifies the external POS terminal identifier.

Example: POS-DEVICE-001

Example:"POS-DEVICE-001"

baseAmountnumber or null, (double), decimal places <= 2required

Specifies the transaction amount (in USD).

Examples:
125
125.5
125.50

Example:125.5

currencyCodestring or nullrequired

Specifies the transaction's currency code (in uppercase ISO 4217 currency code).

Example: USD

Example:"USD"

terminalIdstring, (uuid)required

Specifies the terminal identifier that handles the transaction.

The terminal must be in semi-integrated mode and available (online and ready). A semi-integrated terminal is one that is connected to a POS system, typically through a network or cable.

Example: 0dfac966-9dbd-4608-a65f-d6a4c961dd35

Example:"0dfac966-9dbd-4608-a65f-d6a4c961dd35"

waitForAcceptanceByTerminalboolean

Specifies the response mode is either short or long polling.

If true, specifies long polling. HTTP response will be provided once the terminal accepts or declines to initiate the transaction or a timeout happens (terminal does not respond).
If false, specifies short polling. HTTP response will be returned immediately, while the terminal is still receiving the transaction request.

After either case, use GET /v2/pos/transactions/{{posTransactionId}} to retrieve the latest information of the transaction submission.

This must be false for an initiationChannel of Deeplink.

Polling refers to how the POS application checks Flute for the status or result of a payment after initiating it. The choice is mainly about how quickly the final transaction status is needed and how much repeated traffic can be tolerated.

Short polling The POS application repeatedly sends separate status requests at short intervals. This checks for the completion status of the transaction. Each request gets an immediate response, and the POS application keeps asking until the transaction reaches a final state or times out. Short polling is useful when the POS application can itself periodically check status instead of maintaining an open request. Examples include checking whether an earlier transaction eventually completed, recovering after a connection interruption, or reconciling a transaction whose final state is uncertain.

Long polling The POS application sends a status request, and Flute holds that request open while waiting for the transaction state to change. Once there's a result or the request times out, Flute responds. The POS application can then open another long-poll request if necessary. Long polling is useful when the POS application is actively waiting for a transaction to complete. For example, when the customer has tapped their card and the POS application is waiting to show whether the payment was approved or declined.

Example: true

Default:false

Example:true

requestPaymentMethodStorageConsentboolean

Specifies displaying a message confirming saving the customer payment method information on the terminal.

If true, display a message confirming saving the customer payment method.
If false, does not display a message confirming saving the customer payment method.

Example: true

Default:false

Example:true

initiationChannelstring

Identifies the capture method.

Capture is the step that converts an authorization, funds reserved before a transaction, into an actual charge or funds captured for settlement.

Possible values:

Value	Description
Cloud	Specifies communications by pushing through the cloud. Flute's backend sends (pushes) the transaction request to the physical terminal device over Flute's own cloud connection. The terminal maintains a persistent link to Flute's servers. The transaction details arrive there without the merchant's POS application having to talk to the terminal directly.
Deeplink	Specifies communications by calling the POS software application terminal's payment directly on the device. This is through a deep link or URL scheme such as a local, on-device handoff rather than a round-trip through Flute's cloud. `waitForAcceptanceByTerminal` must be `false` for Deeplink.

Example: Cloud

Default:"Cloud"

Enum:"Cloud""Deeplink"

Example:"Cloud"

extraAmountsobject

Identifies the extra amounts for the transaction.

To accept tips, the merchant is required to have tips enabled and tip-adjustment disabled. If tip collection is enabled and committed at creation time, the tip gets prompted to the customer directly on the device.

referenceIdstring or null, [ 0 .. 36 ] characters

Specifies a reference identifier provided by the merchant.

This is included in the duplicate-check key. It allows the same card and amount combination to be charged multiple times when the reference identifiers are different.

Example: REF-EXT-12345

Example:"REF-EXT-12345"

paymentProcessorIdstring or null, (uuid)

Identifies the payment processor.

Defaults to merchant's default processor.

Example: 76215e54-a85b-4d42-9553-163fe393cb02

Example:"76215e54-a85b-4d42-9553-163fe393cb02"

customerIdstring or null, (uuid)

Identifies the customer to link this payment method to.

This value may be null when this payment method is an orphan owned by the merchant directly. An orphan payment method is a payment method in the merchant's vault but has no customer record associated with it.

Example: 8fa8e727-73c6-436e-b56f-6f55aabf3b1c

Example:"8fa8e727-73c6-436e-b56f-6f55aabf3b1c"

pricingTypestring or null

Identifies the type of pricing.

This value is required only when Dual Pricing is enabled.

Valid values are:

Status	Explanation
Card	The transaction uses the card price, which may include a surcharge.
Cash	The transaction uses the cash price, which may include a cash discount.

Example: Card

Enum:"Card""Cash"

Example:"Card"

captureMethodstring

Identifies the capture method.

Capture is the step that converts an authorization, funds reserved before a transaction, into an actual charge or funds captured for settlement.

Possible values:

Value	Description
Auto	The transaction is captured automatically at the same time as authorization or immediately after, with no separate action required.
Manual	The transaction has been authorized. However, an explicit capture request must be made later to actually allocate the money. Care must be taken because if the transaction is never captured, the authorization simply expires and no funds move.

Example: Auto

Default:"Auto"

Enum:"Auto""Manual"

Example:"Auto"

readingMethodstring

Specifies the POS terminal reading type.

Valid Values are:

Method	Explanation
KeyedEntry	Card details are entered manually on the terminal.
Regular	Card details are read by the device, such as by tap, insert, or swipe.

Example: Regular

Enum:"KeyedEntry""Regular"

Example:"Regular"

curl -i -X POST \
  https://sandbox.api.flute.com/v2/pos/transactions \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "posDeviceId": "POS-DEV-014",
    "referenceId": "REF-POS-20260812-001",
    "captureMethod": "Manual",
    "baseAmount": 42.75,
    "pricingType": "Cash",
    "currencyCode": "USD",
    "paymentProcessorId": "7b1e4a2c-9f3d-4e8b-b2a1-5c6d7e8f9a0b",
    "customerId": "3c4d5e6f-7a8b-49c0-8d1e-2f3a4b5c6d7e",
    "terminalId": "f4e3d2c1-b0a9-4f8e-9d7c-6b5a4938271f",
    "waitForAcceptanceByTerminal": false,
    "readingMethod": "KeyedEntry",
    "requestPaymentMethodStorageConsent": true,
    "extraAmounts": {
      "tipAmount": null,
      "tipRate": 15
    }
  }'

Responses

Bodyapplication/json

posTransactionIdstring, (uuid)

Indicates the POS transaction identifier.

Example: f77b4b4d-2f35-4cd2-8631-31318a4713a1

Example:"f77b4b4d-2f35-4cd2-8631-31318a4713a1"

posTransactionStatusstring

Indicates the status of the transaction.

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:"Cancelled""Completed""Failed""InProgress"

Example:"Completed"

createdOnstring, (date-time)

Indicates the date-time (in an ISO 8601 UTC date-time format) the POS transaction was created on.

Example: 2026-01-15T10:30:56.264Z

Example:"2026-01-15T10:30:56.264Z"

modifiedOnstring, (date-time)

Indicates the date-time (in an ISO 8601 UTC date-time format) when the POS transaction was last updated.

Example: 2026-03-16T16:32:58.743Z

Example:"2026-03-16T16:32:58.743Z"

merchantIdstring, (uuid)

Identifies the merchant identifier.

Example: 5611f824-48ef-4255-978d-91ce13953bbd

Example:"5611f824-48ef-4255-978d-91ce13953bbd"

customerIdstring or null, (uuid)

Identifies the customer to link this payment method to.

Example: 8fa8e727-73c6-436e-b56f-6f55aabf3b1c

Example:"8fa8e727-73c6-436e-b56f-6f55aabf3b1c"

terminalIdstring, (uuid)

Indicates the terminal identifier that handles the transaction.

The terminal must be in semi-integrated mode and available (online and ready). A semi-integrated terminal is one that is connected to a POS system, typically through a network or cable.

Example: 0dfac966-9dbd-4608-a65f-d6a4c961dd35

Example:"0dfac966-9dbd-4608-a65f-d6a4c961dd35"

paymentProcessorIdstring or null, (uuid)

Identifies the payment processor.

Defaults to merchant's default processor.

Example: 76215e54-a85b-4d42-9553-163fe393cb02

Example:"76215e54-a85b-4d42-9553-163fe393cb02"

posDeviceIdstring or null, [ 1 .. 36 ] characters

Indicates the external POS terminal identifier.

Example: POS-DEVICE-001

Example:"POS-DEVICE-001"

referenceIdstring or null

External Reference ID

Example:"REF-EXT-12345"

captureMethodstring

Identifies the capture method.

Capture is the step that converts an authorization, funds reserved before a transaction, into an actual charge or funds captured for settlement.

Possible values:

Value	Description
Auto	The transaction is captured automatically at the same time as authorization or immediately after, with no separate action required.
Manual	The transaction has been authorized. However, an explicit capture request must be made later to actually allocate the money. Care must be taken because if the transaction is never captured, the authorization simply expires and no funds move.

Example: Auto

Default:"Auto"

Enum:"Auto""Manual"

Example:"Auto"

transactionIdstring or null, (uuid)

Indicates the attached transaction identifier.

This value is available after processing.

Example: f01339ec-8184-48c7-b58d-0780d6499ef4

Example:"f01339ec-8184-48c7-b58d-0780d6499ef4"

baseAmountnumber or null, (double), decimal places <= 2, >= 0.01

Identifies the base transaction amount (in USD) before adjustments.

Examples:
125
125.5
125.50

Example:125.5

currencyCodestring or null

Identifies the transaction's currency code (in uppercase ISO 4217 currency code).

Example: USD

Default:"USD"

Example:"USD"

extraAmountsobject or null

Identifies the extra amounts for the transaction.

processedAmountnumber or null, (double), decimal places <= 2

Indicates the transaction amount (in USD).

The value will be null until the transaction is completed.

Example: 87.39

Example:87.39

linkedTransactionobject

Indicates an object detailing the related POS transaction.

This value will be null until the transaction is completed.

Response

{
  "posTransactionId": "6f2a8b3c-9d4e-4f1a-8b7c-3e5d6a9f0c1b",
  "createdOn": "2026-08-12T09:15:22.100Z",
  "modifiedOn": "2026-08-12T09:16:05.400Z",
  "merchantId": "746ba4dd-b1b4-47c3-a034-72aa55007e86",
  "customerId": "9f2b1c4d-7e3a-4f8b-90c1-2d3e4f5a6b7c",
  "terminalId": "83a2baf4-2c5a-4326-acd9-65f26e47ac1e",
  "paymentProcessorId": "2e8c8c3e-e034-42db-8169-1b7999a49cd0",
  "posDeviceId": "POS-DEV-014",
  "referenceId": "REF-POS-20260812-001",
  "posTransactionStatus": "Completed",
  "captureMethod": "Manual",
  "transactionId": "cdb041da-90c6-4e03-82cf-3fa1178680ee",
  "baseAmount": 42.75,
  "currencyCode": "USD",
  "extraAmounts": {
    "tipAmount": null,
    "tipRate": 15
  },
  "processedAmount": 49.16,
  "linkedTransaction": {
    "transactionId": "cdb041da-90c6-4e03-82cf-3fa1178680ee",
    "transactionDateTime": "2026-08-12T09:16:04.900Z",
    "transactionStatus": "Captured",
    "cardTokenType": "Network",
    "paymentMethodType": "Card",
    "referenceId": "REF-POS-20260812-001",
    "originalTransactionId": null,
    "processedAmount": 49.16,
    "refundDetails": {
      "refundedAmount": 0,
      "availableRefundAmount": 49.16
    },
    "currencyCode": "USD",
    "pricingType": "Card",
    "paymentProcessorId": "2e8c8c3e-e034-42db-8169-1b7999a49cd0",
    "customerId": "9f2b1c4d-7e3a-4f8b-90c1-2d3e4f5a6b7c",
    "merchantId": "746ba4dd-b1b4-47c3-a034-72aa55007e86",
    "batchId": null,
    "amountBreakdown": {
      "baseAmount": 42.75,
      "tipAmount": null,
      "tipRate": 15,
      "surchargeAmount": null,
      "surchargeRate": null,
      "discountAmount": null,
      "discountRate": null
    },
    "cardDetails": {
      "paymentMethodId": "39a95e35-6d50-45ec-884b-c2417edf005d",
      "maskedCardNumber": "************1111",
      "cardBrand": "Visa",
      "cardType": "Credit",
      "cardProcessedAsType": "Credit",
      "cardDataSource": "EMV",
      "cardholderVerificationMethod": "PIN",
      "emvTags": {
        "ac": "9F2604A1B2C3D4E5F6",
        "tvr": "0000008001",
        "tsi": "6800",
        "aid": "A0000000031010",
        "applicationLabel": "VISA CREDIT",
        "rawTags": null
      }
    },
    "achDetails": null,
    "processorDetails": {
      "mid": "932129304958123",
      "tid": "6095275263",
      "authCode": "VTLMC1",
      "rrn": "59d5df1aa58d4de3969175eeece571c1"
    },
    "declineDetails": null,
    "addressVerificationServiceResponse": {
      "action": "Allow",
      "responseCode": "Y",
      "description": "Address and ZIP match"
    },
    "transactionEvents": [
      {
        "type": "Sale",
        "status": "Approved",
        "amount": 49.16,
        "dateTime": "2026-08-12T09:16:04.900Z",
        "originalTransactionId": null,
        "declineDetails": null
      }
    ],
    "source": {
      "sourceType": "Terminal",
      "sourceId": "83a2baf4-2c5a-4326-acd9-65f26e47ac1e",
      "sourceName": "Front Counter Terminal 3"
    }
  }
}