Capture Transactions

Capture funds from an existing preauthorization once the final amount is known.

What You Learn

When to capture versus reverse a preauth
Request payloads for v1 and v3 capture endpoints
How to supply tax, tip, and surcharge details in the breakdown
Response fields to store for reconciliation

Overview

Only preauthorized transactions can be captured. You may capture the full amount or a partial amount. The v3 capture endpoint is preferred because it supports granular breakdown data and automatic tip adjustments.

Workflow	Recommended Endpoint	Legacy Endpoint
Capture preauth	`POST /v3/payments/{transaction_id}/capture`	`POST /v1/payments/{transaction_id}/capture`

Request Fields

transaction_id – The Koard transaction ID returned by the preauth
amount (optional) – Amount to capture in minor units. Omit to capture the full authorized amount.
breakdown (optional but recommended) – Tax, tip, and surcharge details for reporting
event_id (optional) – Idempotency key for retries

Example Request (v3)

POST /v3/payments/txn_123/capture
Content-Type: application/json
X-Koard-Apikey: <your-api-key>

{
  "amount": 28975,
  "breakdown": {
    "subtotal": 24000,
    "taxAmount": 2100,
    "taxRate": 0.0875,
    "tipAmount": 2500,
    "tipType": "fixed",
    "surchargeAmount": 375,
    "surchargeRate": 0.0156
  },
  "event_id": "capture-28975"
}

Tip adjustments: Include an updated breakdown to reflect finalized tip amounts. v3 automatically updates tax, tip, and surcharge aggregates on the transaction.

Partial Captures

If you need to capture less than the authorized amount (e.g., partial shipment), set amount accordingly. Any remaining funds can be captured later or released with a reverse.

Responses

Captures return an updated Transaction object with:

status set to captured
Updated total_amount
tip_amount, tax_amount, and surcharge_amount aligned with the capture
captured_amount in downstream settlement reports

Related Operations

Incremental Auth – Increase authorization before capture
Tip Adjust – Adjust gratuity after a preauth but before capture
Refund – Return funds after capture