# Creates a POS transaction

<a id="flute-v2-post-pos-transactions"></a>
<span class="api-endpoint">POST {{<a href="#urlbases">baseURL</a>}}/v2/pos/transactions</span>
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.
<span class="api-seealso">See Also:</span><br>
To list POS transactions, see `GET /v2/pos/transactions`.<br>
To retrieve a POS transaction by ID, see `GET /v2/pos/transactions/{posTransactionId}`.<br>
To cancel a POS transaction, see `POST /v2/pos/transactions/{posTransactionId}/cancel`.

Endpoint: POST /v2/pos/transactions
Version: V2 Beta
Security: Bearer

## Request fields (application/json):

  - `posDeviceId` (string, required)
    Specifies the external POS terminal identifier.

Example: POS-DEVICE-001
    Example: POS-DEVICE-001

  - `baseAmount` (number, required)
    Specifies the transaction amount (in USD).

Required when the `TransactionType` is any of the following:
| Transaction Type | Notes |
|  --- | --- |
| Authorization |  |
| Capture |  |
| Refund |  |
| RefundWORef | Refund without reference |
| Sale |  |
| TipAdjustment |  |

Examples:
125
125.5
125.50
    Example: 125.5

  - `currencyCode` (string, required)
    Specifies the transaction's currency code (in ISO 4217 currency code).

Required when the TransactionType is any of the following:
| Transaction Type | Description |
|  --- | --- |
| Authorization |  |
| Capture |  |
| Refund |  |
| RefundWORef | Refund without reference |
| Sale |  |
| TipAdjustment |  |

Example: USD
    Example: USD

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

  - `waitForAcceptanceByTerminal` (boolean, required)
    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.
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, the customer has tapped their card and the POS application is waiting to show whether the payment was approved or declined.
The request stays open until there’s a status change or timeout, so customers get a quick result without the application constantly making new requests.
Example: true
    Example: true

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

  - `extraAmounts` (object)
    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.

  - `extraAmounts.tipAmount` (number)
    Identifies the absolute amount (in USD) of the tip to be added.
If this value is provided, it must be greater than zero.
This amount adds to the base amount of the original transaction.
That transaction must be authorized first (`POST /pay-api/v1/transactions/auth`).
If the tip collection is enabled on the merchant settings and committed during POS transaction creation, the tip will be prompted to the customer directly on the device.

Care must be taken that a value other than zero can be provided to either `tipAmount` or `tipRate`.
A non-zero value cannot be provided to both.

Example: 14.50 (for $14.50)
    Example: 14.5

  - `extraAmounts.tipRate` (number)
    Identifies a tip percentage to be added.
If this value is provided, it must be greater than zero.
This amount adds to the base amount of the original transaction.
That transaction must be authorized first.

Care must be taken that a value other than zero can be provided to either `tipAmount` or `tipRate`.
A non-zero value cannot be provided to both.

Example: 18.50 (for 18.50%)
    Example: 18.5

  - `extraAmounts.discountAmount` (number)
    Identifies the absolute amount (in USD) of discount to be applied.
If this value is provided, it must be greater than zero.

Care must be taken that a value other than zero can be provided to either `discountAmount` or `discountRate`.
A non-zero value cannot be provided to both.

Example: 25 (for $25)
    Example: 25

  - `extraAmounts.discountRate` (number)
    Identifies a percentage of a discount to be applied.
If this value is provided, it must be greater than zero.

Care must be taken that a value other than zero can be provided to either `discountAmount` or `discountRate`.
A non-zero value cannot be provided to both.

Example: 5.5 (for 5.5%)
    Example: 5.5

  - `extraAmounts.surchargeRate` (number)
    Identifies the percent of transaction amount.
Example: 2.5 (for 2.5%)
    Example: 2.5

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

  - `paymentProcessorId` (string)
    Identifies the payment processor.

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

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

  - `pricingType` (string)
    Identifies the type of pricing.
This value is only relevant 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"

  - `captureMethod` (string)
    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
    Enum: "Auto", "Manual"

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

## Response 200 fields (application/json):

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

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

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

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

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

  - `merchantId` (string)
    Identifies the merchant identifier.

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

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

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

  - `paymentProcessorId` (string)
    Identifies the payment processor.

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

  - `posDeviceId` (string)
    Indicates the external POS terminal identifier.

Example: POS-DEVICE-001
    Example: POS-DEVICE-001

  - `referenceId` (string)
    External Reference ID
    Example: REF-EXT-12345

  - `captureMethod` (string)
    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
    Enum: "Auto", "Manual"

  - `transactionId` (string)
    Indicates the attached transaction identifier.

This value is available after processing.

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

  - `baseAmount` (number)
    Identifies the base transaction amount (in USD) before adjustments.
Examples:
125
125.5
125.50
    Example: 125.5

  - `currencyCode` (string)
    Identifies the transaction's currency code (in ISO 4217 currency code).

Example: USD
    Example: USD

  - `extraAmounts` (object)
    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.

  - `extraAmounts.tipAmount` (number)
    Identifies the absolute amount (in USD) of the tip to be added.
If this value is provided, it must be greater than zero.
This amount adds to the base amount of the original transaction.
That transaction must be authorized first (`POST /pay-api/v1/transactions/auth`).
If the tip collection is enabled on the merchant settings and committed during POS transaction creation, the tip will be prompted to the customer directly on the device.

Care must be taken that a value other than zero can be provided to either `tipAmount` or `tipRate`.
A non-zero value cannot be provided to both.

Example: 14.50 (for $14.50)
    Example: 14.5

  - `extraAmounts.tipRate` (number)
    Identifies a tip percentage to be added.
If this value is provided, it must be greater than zero.
This amount adds to the base amount of the original transaction.
That transaction must be authorized first.

Care must be taken that a value other than zero can be provided to either `tipAmount` or `tipRate`.
A non-zero value cannot be provided to both.

Example: 18.50 (for 18.50%)
    Example: 18.5

  - `extraAmounts.discountAmount` (number)
    Identifies the absolute amount (in USD) of discount to be applied.
If this value is provided, it must be greater than zero.

Care must be taken that a value other than zero can be provided to either `discountAmount` or `discountRate`.
A non-zero value cannot be provided to both.

Example: 25 (for $25)
    Example: 25

  - `extraAmounts.discountRate` (number)
    Identifies a percentage of a discount to be applied.
If this value is provided, it must be greater than zero.

Care must be taken that a value other than zero can be provided to either `discountAmount` or `discountRate`.
A non-zero value cannot be provided to both.

Example: 5.5 (for 5.5%)
    Example: 5.5

  - `extraAmounts.surchargeRate` (number)
    Identifies the percent of transaction amount.
Example: 2.5 (for 2.5%)
    Example: 2.5

  - `processedAmount` (number)
    Indicates the transaction amount (in USD).

The value will be null until the transaction is completed.

Example: 87.39
    Example: 87.39

  - `linkedTransaction` (object)
    Indicates an object detailing the related POS transaction.

This value will be null until the transaction is completed.

  - `linkedTransaction.transactionId` (string)
    Indicates the attached transaction identifier.

This value is available after processing.

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

  - `linkedTransaction.transactionDateTime` (string)
    Indicates the timestamp (in an ISO 8601 date-time format) of the transaction.

Example: 2026-05-05T14:30:42.938Z
    Example: 2026-05-05T14:30:42.938Z

  - `linkedTransaction.transactionStatus` (string)
    Indicates the aggregated transaction status.
Valid values are:
| Status | Description |
|  --- | --- |
| Authorized | Payment approved but funds not yet captured. |
| Cancelled | Transaction stopped before it completed. |
| Captured | Approved funds collected from the card. |
| ChargedBack | Cardholder disputed the charge with their bank. |
| Cleared | Funds finished processing and settled. |
| Declined | Payment rejected by the bank or processor. |
| Failed | Transaction could not complete due to an error. |
| Held | Transaction paused and awaiting release. |
| HeldByProcessor | Processor paused the transaction for review. |
| Informational | Record used for reference only, not a live charge. |
| InProgress | Transaction is still processing. |
| PartiallyAuthorized | Only part of the requested amount was approved. |
| Pending | Transaction is waiting for a result. |
| Refunded | Funds returned to the cardholder. |
| Scheduled | Transaction set to run at a future time. |
| Settled | Funds moved from issuer to the merchant account. |
| Verified | Card or account confirmed as valid. |
| Voided | Authorization cancelled before capture. |

Example: Authorized
    Enum: "Authorized", "Captured", "Voided", "Refunded", "Verified", "Settled", "PartiallyAuthorized", "Informational", "Scheduled", "Cancelled", "ChargedBack", "InProgress", "Cleared", "Held", "HeldByProcessor", "Pending", "Declined", "Failed"

  - `linkedTransaction.transactionType` (string)
    Indicates the possible event types.
Valid values are:
| Type | Description |
|  --- | --- |
| Authorization | Authorizes the transaction. |
| Capture | Collects funds from an approved authorization. |
| CardAuthentication | Confirms cardholder identity before payment. |
| Credit | Sends funds back to a cardholder outside a refund. |
| Hold | Pauses a transaction or account temporarily. |
| Refund | Returns funds for a completed sale. |
| Sale | Authorizes and captures payment in one step. |
| Settle | Submits a batch for final processing. |
| TipAdjustment | Adds or changes a tip after the sale. |
| UnHold | Removes a hold and resumes normal activity. |
| Void | Cancels a transaction before it settles. |

Example: Capture
    Enum: "Authorization", "Sale", "Capture", "Void", "Refund", "TipAdjustment", "CardAuthentication", "Hold", "UnHold", "Credit", "Settle"

  - `linkedTransaction.cardTokenType` (string)
    Indicates the type of the token.
Valid values are:
| Type | Meaning |
|  --- | --- |
| Local | Tokenized and stored within Flute's own vault |
| Network | Tokenized through a card network, such as Visa or Mastercard, using their network tokenization services |

Example: Local
    Enum: "Local", "Network"

  - `linkedTransaction.paymentMethodType` (string)
    Identifies the payment method type.
Valid values are:
| Type | Description |
|  --- | --- |
| ACH | Payment made through an ACH bank transfer. |
| Card | Payment made with a credit or debit card. |
| Cash | Payment made with physical currency. |

Example: Card
    Enum: "Card", "ACH", "Cash"

  - `linkedTransaction.referenceId` (string)
    Indicates 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

  - `linkedTransaction.originalTransactionId` (string)
    Indicates the original transaction identifier.
This value will be provided if the current transaction is a card refund.
Otherwise, it will be null or omitted.
Example: 4d5d19c0-7b8c-4d9e-0f1a-2b3c4d5e6f92
    Example: 4d5d19c0-7b8c-4d9e-0f1a-2b3c4d5e6f92

  - `linkedTransaction.refundDetails` (object)
    Indicates an object detailing the refund posture for a transaction that can be refunded.

This value is null on transactions that are themselves refunds or credits.
Those cannot be refunded again.

  - `linkedTransaction.refundDetails.refundedAmount` (number)
    Indicates the total amount (in USD) already refunded against this transaction.
Examples:
56.99
0
    Example: 0

  - `linkedTransaction.refundDetails.availableRefundAmount` (number)
    Indicates the amount (in USD) still refundable.

Example: 120.99
    Example: 120.99

  - `linkedTransaction.refundDetails.isFullyRefunded` (boolean)
    Indicates the amount has been fully refunded.
If `true`, the amount has been fully refunded.
If `false`, the amount has not been fully refunded.
Example: true
    Example: true

  - `linkedTransaction.pricingType` (string)
    Identifies the type of pricing.
This value is only relevant 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"

  - `linkedTransaction.batchId` (string)
    Indicates the batch settlement identifier.

Example: 42df0a13-4bf4-48f8-929c-08a379c0a0d6
    Example: 42df0a13-4bf4-48f8-929c-08a379c0a0d6

  - `linkedTransaction.amountBreakdown` (object)
    Indicates an object detailing the amount breakdown details.

  - `linkedTransaction.amountBreakdown.tipAmount` (number)
    Indicates the absolute amount (in USD) of the tip to be added.
If this value is provided, it must be greater than zero.
This amount adds to the base amount of the original transaction.
That transaction must be authorized first (`POST /pay-api/v1/transactions/auth`).
Example: 14.50 (for $14.50)
    Example: 14.5

  - `linkedTransaction.amountBreakdown.tipRate` (number)
    Indicates a percentage of the tip to be added.
If this value is provided, it must be greater than zero.
This amount adds to the base amount of the original transaction.
That transaction must be authorized first (`POST /pay-api/v1/transactions/auth`).

Care must be taken that a value other than zero can be provided to either `tipAmount` or `tipRate`.
A non-zero value cannot be provided to both.

Example: 18.50 (for 18.50%)
    Example: 18.5

  - `linkedTransaction.amountBreakdown.surchargeAmount` (number)
    Indicates the surcharge amount (in USD) applied.

Care must be taken that a value other than zero can be provided to either `surchargeAmount` or `surchargeRate`.
A non-zero value cannot be provided to both.

Example: 22 (for $22)
    Example: 22

  - `linkedTransaction.amountBreakdown.surchargeRate` (number)
    Indicates the percent of transaction amount.
This value is added to the base amount after `PercentageOffRate` has been applied.

Care must be taken that a value other than zero can be provided to either `surchargeAmount` or `surchargeRate`.
A non-zero value cannot be provided to both.

Example: 2.5 (for 2.5%)
    Example: 2.5

  - `linkedTransaction.amountBreakdown.discountAmount` (number)
    Indicates the absolute amount (in USD) of discount to be applied.
If this value is provided, it must be greater than zero.
This does not include ZCP (zero cost processing) cash-discount amounts.

Care must be taken that a value other than zero can be provided to either `discountAmount` or `discountRate`.
A non-zero value cannot be provided to both.

Example: 25 (for $25)
    Example: 25

  - `linkedTransaction.amountBreakdown.discountRate` (number)
    Indicates a percentage of a discount to be applied.
If this value is provided, it must be greater than zero.
This does not include ZCP (zero cost processing) cash-discount amounts.

Care must be taken that a value other than zero can be provided to either `discountAmount` or `discountRate`.
A non-zero value cannot be provided to both.

Example: 5.5 (for 5.5%)
    Example: 5.5

  - `linkedTransaction.cardDetails` (object)
    Indicates an object detailing card details exposed on transaction responses (masked or non-sensitive fields only).

  - `linkedTransaction.cardDetails.paymentMethodId` (string)
    Indicates the payment method identifier.

This is the identifier of a previously saved ACH account to charge.

Example: 39a95e35-6d50-45ec-884b-c2417edf005d
    Example: 39a95e35-6d50-45ec-884b-c2417edf005d

  - `linkedTransaction.cardDetails.maskedCardNumber` (string)
    Indicates the masked card number.
This displays only the last four numbers.
Example: ************1111
    Example: ************1111

  - `linkedTransaction.cardDetails.cardBrand` (string)
    Indicates the type of the card.
Valid values are:
| Type | Description |
|  --- | --- |
| AmericanExpress | Card issued by American Express network. |
| DinersClub | Card issued by the Diners Club network. |
| Discover | Card issued by the Discover network. |
| JCB | Card issued by the Japan Credit Bureau network. |
| MasterCard | Card issued by the MasterCard network. |
| Unknown | Card type could not be determined. |
| Visa | Card issued by the Visa network. |

Example: Visa
    Enum: "Unknown", "Visa", "MasterCard", "AmericanExpress", "DinersClub", "Discover", "JCB"

  - `linkedTransaction.cardDetails.cardType` (string)
    Indicates the card is either credit or debit.
Valid values are:
| Type | Description |
|  --- | --- |
| Credit | Card draws funds from a credit line. |
| Debit | Card draws funds from a bank account. |
| Unknown | Card funding type could not be determined. |

Example: Credit
    Enum: "Credit", "Debit", "Unknown"

  - `linkedTransaction.cardDetails.cardDataSource` (string)
    Indicates the source of the card (credit or debit).
Valid values are:
| Item | Explanation |
|  --- | --- |
| EMV | Chip read using EMV tags. |
| EMVContactless | Tap chip read using EMV tags. |
| FallbackSwipe | Swipe used after failed chip read. |
| Internet | Virtual terminal or API entry. |
| Manual | Card present, keyed entry. |
| NFC | Contactless tap using EMV tags and track data. |
| Swipe | Magnetic stripe track data read. |

Example: Swipe
    Enum: "Internet", "Swipe", "NFC", "EMV", "EMVContactless", "FallbackSwipe", "Manual"

  - `linkedTransaction.cardDetails.cardholderVerificationMethod` (string)
    Indicates the method the cardholder was authenticated with.
Valid values are:
| Item | Explanation |
|  --- | --- |
| ElectronicSignatureAnalysis | Electronic signature captured and analyzed. |
| ETicketEnvAmex | E-ticket environment specific to American Express. |
| ManualOther | Other manual verification method. |
| ManualSignature | Paper or screen signature obtained. |
| NotAuthenticated | No cardholder verification performed. |
| OfflinePin | Offline PIN verified by card chip, no network. |
| PIN | Online PIN verified by issuer. |
| SystematicOther | Systematic or automated method not listed. |
| Unknown | Verification method is unknown. |

Example: PIN
    Enum: "NotAuthenticated", "PIN", "ElectronicSignatureAnalysis", "ManualSignature", "ManualOther", "Unknown", "SystematicOther", "ETicketEnvAmex", "OfflinePin"

  - `linkedTransaction.cardDetails.emvTags` (object)

  - `linkedTransaction.cardDetails.emvTags.ac` (string)
    Indicates the AC (application cryptogram).

This is the cryptographic value generated by the card chip so the issuer can authenticate the transaction.

Example: A123456789ABCDEF
    Example: A123456789ABCDEF

  - `linkedTransaction.cardDetails.emvTags.tvr` (string)
    Indicates the TVR (terminal verification results).

This is a bitmask showing which checks the terminal ran and the success status of each one.
The individual checks include data authentication, cardholder verification, and risk management.

Example: 0000008000
    Example: 0000008000

  - `linkedTransaction.cardDetails.emvTags.tsi` (string)
    Indicates the TSI (transaction status information).

This is a bitmask showing which processes were actually performed during the transaction.

Example: E800
    Example: E800

  - `linkedTransaction.cardDetails.emvTags.aid` (string)
    Indicates the AID (application identifier).

This identifies the specific card payment application on the chip, such as Visa Credit or Mastercard Debit.

Example: A0000000031010
    Example: A0000000031010

  - `linkedTransaction.cardDetails.emvTags.applicationLabel` (string)
    Indicates the application Label.

This is the human-readable name of that application, often shown on the terminal display.

Example: VISA CREDIT
    Example: VISA CREDIT

  - `linkedTransaction.cardDetails.emvTags.rawTags` (array)
    Indicates the EMV chip transaction data elements, or tags. 

Each data element is identified by its own hex tag number according to the EMV specifications.
For example, the five most commonly needed ones are: ac (9F26), tvr (95), tsi (9B), aid (4F), and applicationLabel (50).
An actual EMV transaction can return many more tags than that, sometimes with dozens of possible values.

This tag array object contains all the returned pairings.

  - `linkedTransaction.cardDetails.emvTags.rawTags.key` (string)
    Indicates the key of the pair.

Example: ac
    Example: ac

  - `linkedTransaction.cardDetails.emvTags.rawTags.value` (string)
    Indicates the value of the pair.

Example: 9F26
    Example: 9F26

  - `linkedTransaction.achDetails` (object)
    ACH account details exposed on transaction responses (masked or non-sensitive fields only).

  - `linkedTransaction.achDetails.maskedAccountNumber` (string)
    Indicates the masked ACH account number.
This displays only the last four numbers.
Example: ************1111
    Example: ************1111

  - `linkedTransaction.achDetails.accountRoutingNumber` (string)
    Specifies the ACH's account routing number.

Example: 021000021
    Example: 021000021

  - `linkedTransaction.achDetails.accountHolderType` (string)
    Identifies the holder type of the account.
Valid values are:
| Type | Description |
|  --- | --- |
| Business | Card issued to a business or company account. |
| Personal | Card issued to an individual for personal use. |

Example: Business
    Enum: "Business", "Personal"

  - `linkedTransaction.achDetails.accountType` (string)
    Identifies the type of the account.
Valid values are:
| Type | Description |
|  --- | --- |
| Checking | Account used for regular daily transactions. |
| Savings | Account used to hold and grow funds over time. |

Example: Checking
    Enum: "Checking", "Savings"

  - `linkedTransaction.achDetails.secCode` (string)
    Indicates the ACH SEC (standard entry class) code.
Valid values are:
| Code | Description |
|  --- | --- |
| CCD | Used for business to business payments. |
| PPD | Used for consumer payments like payroll or bill pay. |
| Web | Used for a payment authorized on a website. |

Example: CCD
    Enum: "Web", "PPD", "CCD"

  - `linkedTransaction.achDetails.isSameDayProcessing` (boolean)
    Indicates same-day ACH processing for faster settlement.
If `true`, the transaction uses the same-day ACH processing.
If `false`, the transaction does not use the same-day ACH processing.
If null or omitted, the default standard ACH processing is used..
Example: true
    Example: true

  - `linkedTransaction.achDetails.requesterIpAddress` (string)
    Specifies the IP address of the end user.
Valid IP address formats are:
IPv4
IPv6 format3
This end user may be the customer, operator, or application responsible for submitting the transaction.
This is required for audit and fraud-detection purposes.
Example: 192.168.1.1
    Example: 192.168.1.1

  - `linkedTransaction.processorDetails` (object)
    Payment processor identifiers for a transaction.

  - `linkedTransaction.processorDetails.mid` (string)
    Indicates the MID (merchant identifier) assigned by the processor.

Example: 932129304958123
    Example: 932129304958123

  - `linkedTransaction.processorDetails.tid` (string)
    Indicates the TID (terminal identifier) assigned by the processor.

example: 6095275263
    Example: 6095275263

  - `linkedTransaction.processorDetails.authCode` (string)
    Indicates the authorization code returned by the processor.

Example: VTLMC1
    Example: VTLMC1

  - `linkedTransaction.processorDetails.rrn` (string)
    Indicates the RRN (retrieval reference number) returned by the processor.

Example: 59d5df1aa58d4de3969175eeece571c1
    Example: 59d5df1aa58d4de3969175eeece571c1

  - `linkedTransaction.declineDetails` (object)
    Indicates an object detailing a declined or failed transaction.
This value is null when the transaction was approved or is pending.

  - `linkedTransaction.declineDetails.code` (string)
    Indicates the decline or failure code from the processor or gateway.

Example: 41
    Example: 41

  - `linkedTransaction.declineDetails.message` (string)
    Indicates a human-readable decline or failure message.

Example: HOLD-CALL
    Example: HOLD-CALL

  - `linkedTransaction.addressVerificationServiceResponse` (object)
    Indicates the AVS (address verification service) response for card payments.

  - `linkedTransaction.addressVerificationServiceResponse.action` (string)
    Indicates allowing an action after address verification.
Valid values are:
| Status | Explanation |
|  --- | --- |
| Allow | If address verification passes, the payment proceeds. |
| Deny | If address verification does not pass, the payment is denied. |

Example: Allow
    Enum: "Allow", "Deny"

  - `linkedTransaction.addressVerificationServiceResponse.responseCode` (string)
    Indicates the AVS (address verification service) response code from processor.

Example: A
    Example: Y

  - `linkedTransaction.addressVerificationServiceResponse.description` (string)
    Indicates the description of the AVS (address verification service) result code description.

Example: Address and ZIP match
    Example: Address and ZIP match

  - `linkedTransaction.transactionEvents` (array)

  - `linkedTransaction.transactionEvents.type` (string)
    Indicates the transaction types.
Valid values are:
| Value | Description |
|  --- | --- |
| Authorization | The transaction reserved funds for a later capture. |
| CardAuthentication | The transaction confirmed the identity of the cardholder. |
| Capture | The transaction collected funds from an earlier authorization. |
| Credit | The transaction sent funds to the payment method without a prior charge. |
| Hold | The transaction placed a temporary hold on funds. |
| Refund | The transaction returned funds from an earlier charge. |
| Sale | The transaction authorized and captured funds together. |
| Settle | The transaction submitted a batch for final processing. |
| TipAdjustment | The transaction changed the tip amount on a prior charge. |
| UnHold | The transaction released a prior hold on funds. |
| Void | The transaction canceled a charge before settlement. |

Example: Credit
    Enum: "Authorization", "Sale", "Capture", "Void", "Refund", "TipAdjustment", "CardAuthentication", "Hold", "UnHold", "Credit", "Settle"

  - `linkedTransaction.transactionEvents.status` (string)
    Indicates the transaction status.
Valid values are:
| Status | Description |
|  --- | --- |
| Approved | Payment passed checks. Funds will move. |
| Declined | Bank or card issuer rejected payment. |
| Failed | Payment attempt ended in error. |
| Pending | Payment is waiting for a result. |

Example: Approved
    Enum: "Pending", "Approved", "Declined", "Failed"

  - `linkedTransaction.transactionEvents.amount` (number)
    Specifies the base amount (in USD) to charge.
For payment sessions (mode of either `SaveMethod` or `PaymentAndSave`), this value must be greater than zero.
For vault-only payment sessions (mode of `SaveMethod`), this value must be zero.
A value of null creates a flexible-amount payment session where the amount is set at checkout.
Examples:
64.99
0
null
    Example: 64.99

  - `linkedTransaction.transactionEvents.dateTime` (string)
    Indicates the date-time (in an ISO 8601 date-time format) of the event.

Example: 2026-05-05T14:30:42.938Z
    Example: 2026-05-05T14:30:42.938Z

  - `linkedTransaction.transactionEvents.declineDetails` (object)
    Indicates an object detailing a declined or failed transaction.
This value is null when the transaction was approved or is pending.

  - `linkedTransaction.transactionEvents.declineDetails.code` (string)
    Indicates the decline or failure code from the processor or gateway.

Example: 41
    Example: 41

  - `linkedTransaction.transactionEvents.declineDetails.message` (string)
    Indicates a human-readable decline or failure message.

Example: HOLD-CALL
    Example: HOLD-CALL

  - `linkedTransaction.source` (object)
    Indicates an object describing the origination of the transaction.

  - `linkedTransaction.source.sourceType` (string)
    Indicates the source of the transaction.
Valid values are:
| Value | Description |
|  --- | --- |
| ApiKey | An external application created the transaction using an API key. |
| Invoice | A billed invoice created the transaction. |
| MobileApp | A mobile application created the transaction. |
| Portal | A staff member created the transaction through the web portal. |
| QuickPayment | A one-time payment link created the transaction. |
| Subscription | A recurring subscription created the transaction. |
| TapToPay | A mobile device using tap to pay created the transaction. |
| Terminal | A physical payment terminal created the transaction. |
| WebComponent | An embedded web component created the transaction. |

Example: QuickPayment
    Enum: "Portal", "ApiKey", "Terminal", "Invoice", "QuickPayment", "WebComponent", "Subscription", "MobileApp", "TapToPay"

  - `linkedTransaction.source.sourceId` (string)
    Indicates the Identifier of the originating entity.

Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
    Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6

  - `linkedTransaction.source.sourceName` (string)
    Indicates a human-readable name of the originator.

Example: API Key for ecommerce app
    Example: API Key for ecommerce app

## 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

  - `title` (string)

  - `cause` (string)

  - `resolution` (string)

  - `documentationUrl` (string)
    https://developer.flute.com/

## Response 401 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

  - `title` (string)

  - `cause` (string)

  - `resolution` (string)

  - `documentationUrl` (string)
    https://developer.flute.com/

## Response 402 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

  - `title` (string)

  - `cause` (string)

  - `resolution` (string)

  - `documentationUrl` (string)
    https://developer.flute.com/

## Response 403 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

  - `title` (string)

  - `cause` (string)

  - `resolution` (string)

  - `documentationUrl` (string)
    https://developer.flute.com/

## Response 404 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

  - `title` (string)

  - `cause` (string)

  - `resolution` (string)

  - `documentationUrl` (string)
    https://developer.flute.com/

## Response 429 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

  - `title` (string)

  - `cause` (string)

  - `resolution` (string)

  - `documentationUrl` (string)
    https://developer.flute.com/

## Response 500 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

  - `title` (string)

  - `cause` (string)

  - `resolution` (string)

  - `documentationUrl` (string)
    https://developer.flute.com/