# Transactions

A transaction is created every time a merchant charges a card or debits an ACH account.

This guide walks through the full transaction lifecycle for a card payment, start to finish: calculating the amount, creating the transaction, capturing it, adjusting the tip, looking it up, sharing the receipt, and reversing or refunding it. ACH-only steps (holding and releasing a pending ACH transaction) are documented at the end for reference.

## Transaction Endpoints

| Endpoint | Description |
|  --- | --- |
| `GET /v2/transactions` | List transactions. |
| `POST /v2/transactions` | Create a transaction. |
| `GET /v2/transactions/{transactionId}` | Retrieve a transaction by ID. |
| `POST /v2/transactions/calculate-amount` | Calculate the total amount before creating a transaction. |
| `POST /v2/transactions/{transactionId}/capture` | Capture a previously authorized transaction. |
| `POST /v2/transactions/{transactionId}/tip-adjustment` | Adjust the tip on an authorized or captured card transaction. |
| `POST /v2/transactions/{transactionId}/share-receipt` | Send a transaction receipt by SMS. |
| `POST /v2/transactions/{transactionId}/reversal` | Reverse or refund a specific transaction. |
| `POST /v2/transactions/reversal` | Refund or return funds without referencing a specific transaction. |
| `POST /v2/transactions/credit` | Issue a credit without referencing a specific transaction. |
| `POST /v2/transactions/{transactionId}/ach-hold` | Place a hold on a pending ACH transaction. |
| `POST /v2/transactions/{transactionId}/ach-release` | Release a held ACH transaction. |


## Card Transaction Workflow

Follow these steps to process a card transaction from start to finish.

### Step 1 — Calculate the amount

This step is optional but recommended when the merchant uses zero cost processing (dual pricing, cash discounts, or credit card surcharges).

Call `POST /v2/transactions/calculate-amount` with the base amount, currency, and pricing type.

The response breaks the total out by tender type (`cash`, `creditCard`, `debitCard`, `ach`), so the merchant can display the correct amount before the customer pays.

```json
{
  "baseAmount": 100.00,
  "currencyCode": "USD",
  "pricingType": "Card",
  "discountAmount": 0,
  "discountRate": 5,
  "surchargeRate": 2.5,
  "tipAmount": 15,
  "tipRate": 0
}
```

### Step 2 — Create the transaction

Call `POST /v2/transactions` with the payment processor, the amount, and the card details.

Two decisions shape this step:

* **Saved card vs. new card.** Pass a saved `paymentMethodId`, or supply the card number, security code, and expiration inline. `billingAddress` and `contactInfo` are optional for a saved card, but populating them for a new card improves processor acceptance.
* **`captureMethod`: `Auto` or `Manual`.** `Auto` authorizes and captures in the same call, so the transaction lands in an `Approved` state immediately. `Manual` only authorizes the funds and returns a `Pending` transaction; capture it later with Step 3.


```json
{
  "paymentProcessorId": "a2f2c2e7-0b23-4682-8f99-ab7707205461",
  "baseAmount": 100.00,
  "currencyCode": "USD",
  "referenceId": "REF-CARD-SALE-001",
  "isCustomerInitiatedTransaction": true,
  "pricingType": "Card",
  "transactionDetails": {
    "cardData": {
      "captureMethod": "Manual",
      "paymentMethodId": "e397e367-bc4a-4b69-bd78-32e3e12327c2"
    }
  }
}
```

The response returns the `transactionId` needed for every subsequent step.

### Step 3 — Capture the transaction

Skip this step if Step 2 used `captureMethod: Auto`.

Call `POST /v2/transactions/{transactionId}/capture` to settle a transaction that was authorized with `captureMethod: Manual`. This is the point where a merchant confirms inventory or finalizes an order total before the money actually moves.

Omit the request body for a full capture, or pass a smaller `amount` for a partial capture (up to the original authorized amount).

```json
{
  "amount": 50
}
```

A processor decline on capture returns a 402 error.

### Step 4 — Adjust the tip

This step is optional and only applies to card-present transactions that use a credit card (not debit), where the tip is added after the initial swipe, such as a restaurant closing a tab.

Call `POST /v2/transactions/{transactionId}/tip-adjustment` before the transaction is captured or settled. Both `merchant.IsTipsEnabled` and `merchant.IsTipAdjustmentEnabled` must be turned on for the merchant.

```json
{
  "tipAmount": 22.75,
  "tipRate": 0
}
```

Only one of `tipAmount` or `tipRate` can be non-zero in a given request.

### Step 5 — Look up the transaction

Use `GET /v2/transactions/{transactionId}` to retrieve the full details of a single transaction, including its `amountBreakdown`, `processorResponse`, and `addressVerificationServiceResponse`.

Use `GET /v2/transactions` to list transactions with filters such as `fromDate`, `toDate`, `paymentMethodType`, `customerId`, and `referenceId`. This endpoint returns a summarized view; use the single-transaction endpoint above for full detail.

### Step 6 — Share the receipt

This step is optional.

Call `POST /v2/transactions/{transactionId}/share-receipt` to text a receipt to the customer.

```json
{
  "mobilePhoneNumber": "+15551234567",
  "hasCustomerConsent": true
}
```

`hasCustomerConsent` must be `true`, or the request is rejected. The `mobilePhoneNumber` does not have to match the number on the original transaction; a receipt can go to any number the customer provides.

### Step 7 — Reverse or refund the transaction

This step is optional and only needed if the transaction needs to be reversed or refunded.

Call `POST /v2/transactions/{transactionId}/reversal` to reverse or refund a specific transaction. The payment method (card or ACH) is auto-detected from the original transaction.

Pass an `amount` for a partial refund, or omit it for a full reversal.

```json
{
  "amount": 25
}
```

### Step 8 — Issue an unreferenced refund or credit (optional)

Use these endpoints only when there's no Flute transaction to reference, such as a sale that was originally processed outside Flute.

Unreferenced refunds and credits are high-risk transaction types. Funds are returned directly from the merchant's account, even when the original sale was never processed through Flute.

* `POST /v2/transactions/reversal` — refunds or returns funds without a reference to a prior transaction.
* `POST /v2/transactions/credit` — issues a credit without a reference to a prior transaction.


Both endpoints take the same request shape: the processor, the amount, and either a saved payment method or raw card or ACH account details. Saved payment methods are not supported for either endpoint; only raw card or ACH details can be used.

```json
{
  "paymentProcessorId": "7538ed96-b5ec-488e-94a0-b44ef5e77833",
  "baseAmount": 100.00,
  "currencyCode": "USD",
  "referenceId": "ext-ref-123",
  "creditDetails": {
    "cardData": {
      "paymentMethodDetails": {
        "cardNumber": "4111111111111111",
        "securityCode": "123",
        "expirationMonth": 12,
        "expirationYear": 2033
      }
    }
  }
}
```

## ACH-Specific Steps

The following two endpoints only apply to ACH transactions and are not part of the card workflow above.

### Holding an ACH transaction

Call `POST /v2/transactions/{transactionId}/ach-hold` to place a hold on a pending ACH transaction, for example, while a dispute is investigated.

### Releasing an ACH transaction

Call `POST /v2/transactions/{transactionId}/ach-release` to release a previously held ACH transaction.

## Next Steps

* **Settlement** — a captured transaction eventually settles and appears in a settlement batch. See `POST /v2/settlements/settle` and `GET /v2/settlements/batches`.
* **[Webhooks](/docs/getting-started/webhooks)** — subscribe to `transaction.card.*` and `transaction.ach.*` event types to get notified as a transaction moves through this lifecycle.