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.

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

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.

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

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.

{
  "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.

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).

{
  "amount": 50
}

A processor decline on capture returns a 402 error.

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.

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

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

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.

This step is optional.

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

{
  "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.

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.

{
  "amount": 25
}

Use these endpoints only when there's no Flute transaction to reference, such as a sale that was originally processed outside 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.

{
  "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
      }
    }
  }
}

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

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

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

• Settlement — a captured transaction eventually settles and appears in a settlement batch. See POST /v2/settlements/batches/close and GET /v2/settlements/batches.
• Webhooks — subscribe to transaction.card.* and transaction.ach.* event types to get notified as a transaction moves through this lifecycle.