# Creates a POS transaction

<span class="api-endpoint">POST {{<a href="#urlbases">baseURL</a>}}/pos-api/v1/pos-transactions</span>
Initiate a new transaction on the terminal device with predefined information, such as amount and transaction type.

Endpoint: POST /pos-api/v1/pos-transactions
Version: V1
Security: Bearer

## Request fields (application/json):

  - `amount` (number, required)
    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
    Example: 45.99

  - `currencyId` (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

  - `posDeviceId` (string, required)
    Specifies the External POS (point of sale) device identifier.

Example: 000000001
    Example: 000000001

  - `terminalId` (string, required)
    Specifies the terminal identifier.

This is the 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

  - `transactionTypeId` (integer, 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

  - `waitForAcceptanceByTerminal` (boolean, required)
    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

  - `requestPaymentMethodStorageConsent` (boolean)
    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
    Example: true

  - `targetTransactionId` (string, 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

  - `referenceId` (string)
    Specifies the external transaction reference identifier.

  - `useCardPrice` (boolean)
    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.

  - `paymentProcessorId` (string)
    Set the Payment Processor ID to be used in the transaction. If not provided, it will use the merchant's default processor.

  - `customerId` (string)
    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

  - `readingMethodId` (integer)
    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

## Response 200 fields (application/json):

  - `posTransactionId` (string)
    Indicates the POS transaction identifier.

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

  - `statusId` (integer)
    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

  - `status` (string)
    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 400 fields (application/json):

  - `details` (string)
    Indicates details about the error.

Example: Validation failed: -- Email: 'Email' is not a valid email address. Severity: Error
    Example: Validation failed: -- Email: 'Email' is not a valid email address. Severity: Error

  - `statusCode` (integer)
    Specifies the HTTP response status code.
This is the HTTP status code returned by the attempted delivery.
The following is a list of HTTP response status codes that include but are not limited to:
| HTTP Status | Meaning |
|  --- | --- |
| 200 | Delivery succeeded |
| 400 | Bad request |
| 401 | Unauthorized |
| 404 | Endpoint not found |
| 429 | Rate limited |

Example: 401
    Example: 401

  - `source` (string)
    Indicates the source of the error.
Example: <Service>
    Example: <Service>

  - `exceptionType` (string)
    Indicates the error's exception type.

Example: FluentValidation.ValidationException
    Example: FluentValidation.ValidationException

  - `correlationId` (string)
    Indicates the correlation identifier.

Example: aa6cfcd0-0295-4a4c-b074-8c901f114fef
    Example: aa6cfcd0-0295-4a4c-b074-8c901f114fef

  - `entityId` (string)
    Indicates the entity identifier.
Example:
null

  - `errorCode` (string)
    Indicates the error code.
Example:
null

## Response 404 fields (application/json):

  - `details` (string)

  - `statusCode` (integer)
    Specifies the HTTP response status code.
This is the HTTP status code returned by the attempted delivery.
The following is a list of HTTP response status codes that include but are not limited to:
| HTTP Status | Meaning |
|  --- | --- |
| 200 | Delivery succeeded |
| 400 | Bad request |
| 401 | Unauthorized |
| 404 | Endpoint not found |
| 429 | Rate limited |

Example: 401
    Example: 401

  - `source` (string)

  - `exceptionType` (string)

  - `correlationId` (string)

  - `entityId` (string)

  - `errorCode` (string)

## Response 500 fields (application/json):

  - `details` (string)

  - `statusCode` (integer)
    Specifies the HTTP response status code.
This is the HTTP status code returned by the attempted delivery.
The following is a list of HTTP response status codes that include but are not limited to:
| HTTP Status | Meaning |
|  --- | --- |
| 200 | Delivery succeeded |
| 400 | Bad request |
| 401 | Unauthorized |
| 404 | Endpoint not found |
| 429 | Rate limited |

Example: 401
    Example: 401

  - `source` (string)

  - `exceptionType` (string)

  - `correlationId` (string)

  - `entityId` (string)

  - `errorCode` (string)