Creates a POS transaction

Request

POST {{baseURL}}/pos-api/v1/pos-transactions

This endpoint creates a POS transaction.

It initiates a new transaction on the terminal device with predefined information, such as amount and transaction type.

See Also:
To list POS transactions, see GET /pos-api/v1/pos-transactions.
To retrieve a POS transaction by ID, see GET /pos-api/v1/pos-transactions/{id}.
To cancel a POS transaction, see POST /pos-api/v1/pos-transactions/{id}/cancel.
To print a POS transaction receipt, see POST /pos-api/v1/pos-transactions/{posTransactionId}/print.

Security

Bearer

Bodyapplication/json

amountnumber or null, (integer), decimal places <= 2, >= 0.01required

Specifies the total transaction amount (in USD).

This is required when `transactionTypeId` is:

Id	Type	Remark
1	Authorization
2	Sale
7	RefundWORef	Refund without reference. As a warning, these are considered high-risk transaction types, as funds are debited directly from the merchant's account even if the original sale was not processed through Flute.
8	TipAdjustment

Example: 45.99 (for $45.99)

Example:45.99

currencyIdinteger or null, (integer)required

Specifies the Flute currency identifier.

Always set to 1.

This is required when transactionTypeId is:

Id	Type	Remark
1	Authorization
2	Sale
7	RefundWORef	Refund without reference. As a warning, these are considered high-risk transaction types, as funds are debited directly from the merchant's account even if the original sale was not processed through Flute.
8	TipAdjustment

Example: 1

Example:1

posDeviceIdstring, [ 1 .. 36 ] charactersrequired

Specifies the External POS (point of sale) device identifier.

Example: 000000001

Example:"000000001"

terminalIdstring, (uuid)required

Specifies the terminal identifier.

This is the terminal used to initiate and handle the transaction.

This terminal must be in the semi-integrated mode and available (online and ready).

Example: 914358ab-efd7-4c5c-8570-fe4c0370fc37

Example:"914358ab-efd7-4c5c-8570-fe4c0370fc37"

transactionTypeIdinteger, (int32)required

Set the transaction type to be processed by the terminal.

Possible values:

Id	Type	Remarks
1	Authorization
2	Sale
3	Capture
4	Void
5	Refund
6	CardAuthentication
7	RefundWORef	Refund without reference. As a warning, these are considered high-risk transaction types, as funds are debited directly from the merchant's account even if the original sale was not processed through Flute.
8	TipAdjustment
10	Settle

Example: 10

Example:10

waitForAcceptanceByTerminalbooleanrequired

Specifies the long polling response mode.

If true, use the long pooling response mode. The HTTP response will be provided once the terminal either:

accepts or declines to initiate the transaction
times out (terminal does not respond).

If false, use the short pooling response mode. The HTTP response will be returned immediately, while the terminal is still receiving the transaction request.

In either result, use Gets POS transaction by ID (GET {{baseURL}}/pos-api/v1/pos-transactions/{{posTransactionsid}}) to retrieve the latest information of the transaction submission.

Example: true

Example:true

requestPaymentMethodStorageConsentboolean

Specifies showing a popup about saving customer payment method information on the terminal.

If true, show a popup about saving customer payment method information on the terminal.
If false, do not show a popup about saving customer payment method information on the terminal.

Example: true

Default:false

Example:true

targetTransactionIdstring or null, (uuid)required

Specifies the transaction identifier.

This is required for the following operations:

Capture
Void
Refund
TipAdjustment

Example: 250521bd-1e4e-4363-8381-de512760d19a

Example:"250521bd-1e4e-4363-8381-de512760d19a"

referenceIdstring or null, [ 0 .. 36 ] characters

Specifies the external transaction reference identifier.

useCardPriceboolean or null

Set the type of price being sent in the amount parameter.

This field is mandatory only if the merchant's ZeroCostProcessingOption is Dual Pricing. For other ZeroCostProcessingOption values, set it as null.

If ZeroCostProcessingOption is Dual Pricing, set useCardPrice=true.
If the amount contains the card price, or useCardPrice=false.
If the amount contains the cash price.

The application will automatically calculate the total amounts by each payment method based on these inputs.

paymentProcessorIdstring or null, (uuid)

Set the Payment Processor ID to be used in the transaction. If not provided, it will use the merchant's default processor.

customerIdstring or null, (uuid)

Specifies the customer identifier.

This is used when saving the payment method.
If this value is provided, the payment method is saved to the specified customer.
If this value is not provided, a new customer record is created.

Example: fd9198a4-eb6f-4620-9603-4f4638289de5

Example:"fd9198a4-eb6f-4620-9603-4f4638289de5"

readingMethodIdinteger or null, (int32)

Set the credit card reading method for the transaction.

Possible values:

Value	Name	Description
1	Reading	Regular card reading method (Tap, Insert or Swipe) [default]
2	KeyedIn	Manual entry of card details (Keyed-in)

Example: 1

Example:1

curl -i -X POST \
  https://developer.flute.com/_mock/api-reference/pos-api/v1/pos-transactions \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "posDeviceId": "000000001",
    "referenceId": "10001",
    "transactionTypeId": 2,
    "targetTransactionId": null,
    "amount": 10,
    "useCardPrice": null,
    "currencyId": 1,
    "paymentProcessorId": "d9c3a8b1-6e2d-4f7c-a1b2-3c4d5e6f7a81",
    "terminalId": "3a7c9d1e-5b2f-4c8a-9d7e-1a2b3c4d5e92",
    "customerId": null,
    "waitForAcceptanceByTerminal": false,
    "readingMethodId": null,
    "requestPaymentMethodStorageConsent": false
  }'

Responses

Bodyapplication/json

posTransactionIdstring, (uuid)

Indicates the POS transaction identifier.

Example: 102ae6f7-8a9b-4c0d-1e2f-3a4b5c6d7

Example:"102ae6f7-8a9b-4c0d-1e2f-3a4b5c6d7"

statusIdinteger, (int32)

Indicates the value of the status identifier.

Possible values:

Value	Name
1	TerminalConnecting
2	TransactionProcessing
3	DeclinedByProcessor
4	CancelByPos
5	CancelByTerminal
6	Completed
7	Error
8	Inconsistency
9	TerminalOffline
10	TransactionSentToProcessor

Example: 2

Example:2

statusstring or nullread-only

Indicates the status identifier.

Possible values:

Name	Value
TerminalConnecting	1
TransactionProcessing	2
DeclinedByProcessor	3
CancelByPos	4
CancelByTerminal	5
Completed	6
Error	7
Inconsistency	8
TerminalOffline	9
TransactionSentToProcessor	10

Example: TransactionProcessing

Example:"TransactionProcessing"

Response

{
  "posTransactionId": "6f1a2b3c-4d5e-4f6a-b7c8-9d0e1f2a3b03",
  "statusId": 1,
  "status": "TerminalConnecting"
}