Incremental Authorizations

Increase the amount of an existing preauthorization to cover additional charges.

What You Learn

When incremental auths are required
Differences between v1 and v3 auth endpoints
How to send updated breakdown data with floating-point rates and surcharge information
Best practices for idempotency and reconciliation

When to Use Incremental Auth

Use incremental authorizations any time the ticket total grows after the initial preauth—for example:

Guests add items to a restaurant tab
Hotel guests incur additional room charges
Rental agreements need extra security deposits

Workflow	Recommended Endpoint	Legacy Endpoint
Incremental auth	`POST /v3/payments/{transaction_id}/auth`	`POST /v1/payments/{transaction_id}/auth`

The v3 endpoint supports detailed breakdown data and proportional surcharge calculations.

Payload Structure

transaction_id – The original preauth transaction ID
amount – Additional amount to authorize in minor units (cents)
breakdown (optional but recommended) – Updated subtotal, tax, tip, and surcharge
event_id (optional) – Idempotency key for retries

Example Request (v3)

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

{
  "amount": 4500,
  "breakdown": {
    "subtotal": 4000,
    "taxAmount": 350,
    "taxRate": 0.0875,
    "tipAmount": 150,
    "tipType": "percentage",
    "surchargeAmount": 0,
    "surchargeRate": 0.0
  },
  "event_id": "auth-bump-4500"
}

Match surcharge policy: If the merchant applies surcharges, include both surchargeAmount and surchargeRate so downstream totals stay consistent.

Response Details

Incremental auths return an updated Transaction object with:

Increased total_amount
Updated authorized_amount on downstream reports
Status authorized until the transaction is captured or reversed

What Happens Next

Use Capture to finalize the full amount.
If the additional charges fall through, issue a Reverse for the newly authorized funds.
Tip changes after the guest signs can be handled with Tip Adjust.