Reverses a POS transaction

Request

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

This endpoint reverses a POS transaction.

Provide the originalTransactionId to reverse a specific transaction. Only card transactions can be reversed this way. The gateway resolves whether the reversal is a void or a refund, based on the transaction's settlement status. A void reverses the full amount. A refund honors reversalAmount as an optional cap for a partial refund.

Omit originalTransactionId to create an unreferenced refund. An unreferenced refund requires reversalAmount and currencyCode.

A void, or a referenced credit-card refund, resolves in the cloud and completes synchronously. A debit-card referenced refund, or any unreferenced refund, requires the customer to present their card again on the terminal and resolves asynchronously. Use GET /v2/pos/transactions/{{posTransactionId}} until posTransactionStatus reaches a terminal state, such as Completed, Failed, or Cancelled.

This endpoint is idempotent. See the idempotency-key header entry. For more information, see Idempotency.

This endpoint requires a merchant API token. A partner API token will result in a permissions error including possibly a 403 response.

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 create a new POS transaction, see POST /v2/pos/transactions.
To cancel a POS transaction, see POST /v2/pos/transactions/{posTransactionId}/cancel.

Security

Bearer

Headers

idempotency-keystring, (uuid), <= 255 characters

Specifies the client-generated idempotency-key.

This key is optional. We recommend using the key to prevent multiple invocations of the operation. This key makes this request safely retryable, or idempotent. If the idempotency key is not included, the call will not have idempotency protection.

A retry with the same key, made within the retention window, returns the original response verbatim. The operation is not repeated. The retention window, also called the TTL (time to live) is 1440 minutes (24 hours) by default but this setting may be changed.

A retry with the same key while the original request is still processing returns 409 Conflict (IdempotencyKeyInProgress). Retry again after a short delay.

Reusing the same key with a different request body returns 422 Unprocessable Content (IdempotencyKeyConflict). Generate a new key for each distinct operation.

A 500 series server error is not stored against the key. A retry with the same key after a 500 series response processes the request again.

Example:6a1f7e2c-4b3d-4e5a-8f9c-1d2e3f4a5b6c

Bodyapplication/jsonrequired

terminalIdstring, (uuid)required

Specifies the terminal identifier that handles the reversal.

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

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

posDeviceIdstring, [ 1 .. 36 ] charactersrequired

Specifies the external POS terminal identifier.

Example: POS-DEVICE-001

Example:"POS-DEVICE-001"

referenceIdstring, [ 1 .. 36 ] charactersrequired

Specifies a reference identifier provided by the merchant.

This value must be unique for merchant.

Example: REF-EXT-12345

Example:"REF-EXT-12345"

originalTransactionIdstring or null, (uuid)

Specifies the transaction identifier to reverse.

If omitted, this creates an unreferenced refund. An unreferenced refund requires the customer to present their card on the terminal. An unreferenced refund also requires reversalAmount and currencyCode.

If provided, this reverses the specified transaction. Only card transactions can be reversed. The terminal resolves whether the reversal is a void or a refund, based on the transaction's settlement status.

Example: 4d5d19c0-7b8c-4d9e-0f1a-2b3c4d5e6f92

Example:"4d5d19c0-7b8c-4d9e-0f1a-2b3c4d5e6f92"

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

Specifies the amount (in USD) to reverse.

This value is required when originalTransactionId is omitted (an unreferenced refund).

This value is optional when originalTransactionId is provided. If provided, this value caps a partial refund. If null or omitted, the full available amount is reversed.

This value is ignored for a void.

Example: 50.24 (for $50.24)

Example:50.24

currencyCodestring or null, <= 3 characters

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

Example: USD

Default:"USD"

Value:"USD"

Example:"USD"

paymentProcessorIdstring or null, (uuid)

Identifies the payment processor.

Defaults to merchant's default processor.

A list of payment processor identifiers for a specified customer can be retrieved with GET /v2/settings/payment-config.

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.

A list of customer identifiers can be retrieved with GET /v2/customers.

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

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

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"

initiationChannelstring, (enum)

Identifies how the transaction reaches the terminal.

Valid values are:

Name	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"

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.

Example: true

Default:false

Example:true

// Language is not supported.

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.

A list of customer identifiers can be retrieved with GET /v2/customers.

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.

A list of payment processor identifiers for a specified customer can be retrieved with GET /v2/settings/payment-config.

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

Specifies an external transaction identifier for client-side tracking.

Also used in duplicate control validation. A unique value allows similar transactions to process as distinct, bypassing duplicate blocking when needed.

Example: REF-EXT-12345

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"

initiationChannelstring, (enum)

Identifies how the transaction reaches the terminal.

Valid values are:

Name	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"

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, <= 3 characters

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

Example: USD

Default:"USD"

Value:"USD"

Example:"USD"

extraAmountsobject or null

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.

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

Indicates the transaction amount (in USD).

The value will be null until the transaction is completed.

Examples:
87.39 (for $87.39)
null

Example:87.39

linkedTransactionobject

Indicates an object detailing the related POS transaction.

This value will be null until the transaction is completed.

Response

{
  "posTransactionId": "8b4c7e9a-1f2d-4e3a-9c8b-5d6e7f8a9b0c",
  "createdOn": "2026-08-12T10:05:11.200Z",
  "modifiedOn": "2026-08-12T10:05:13.600Z",
  "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-002",
  "posTransactionStatus": "Completed",
  "captureMethod": "Manual",
  "transactionId": "3d9a2b1c-8e4f-4a7d-b0c9-1e2f3a4b5c6d",
  "baseAmount": 20,
  "currencyCode": "USD",
  "extraAmounts": {
    "tipAmount": null,
    "tipRate": null
  },
  "processedAmount": 20,
  "linkedTransaction": {
    "transactionId": "3d9a2b1c-8e4f-4a7d-b0c9-1e2f3a4b5c6d",
    "transactionDateTime": "2026-08-12T10:05:13.400Z",
    "transactionStatus": "Approved",
    "cardTokenType": "Network",
    "paymentMethodType": "Card",
    "referenceId": "REF-POS-20260812-002",
    "originalTransactionId": "cdb041da-90c6-4e03-82cf-3fa1178680ee",
    "processedAmount": 20,
    "refundDetails": {
      "refundedAmount": 20,
      "availableRefundAmount": 29.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": 20,
      "tipAmount": null,
      "tipRate": null,
      "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": null
    },
    "achDetails": null,
    "processorDetails": {
      "mid": "932129304958123",
      "tid": "6095275263",
      "authCode": "VTLMC2",
      "rrn": "59d5df1aa58d4de3969175eeece571c2"
    },
    "declineDetails": null,
    "addressVerificationServiceResponse": {
      "action": "Allow",
      "responseCode": "Y",
      "description": "Address and ZIP match"
    },
    "transactionEvents": [
      {
        "type": "Refund",
        "status": "Approved",
        "amount": 20,
        "dateTime": "2026-08-12T10:05:13.400Z",
        "originalTransactionId": "cdb041da-90c6-4e03-82cf-3fa1178680ee",
        "declineDetails": null
      }
    ],
    "source": {
      "sourceType": "Terminal",
      "sourceId": "83a2baf4-2c5a-4326-acd9-65f26e47ac1e",
      "sourceName": "Front Counter Terminal 3"
    }
  }
}