Tip Adjustments

Update gratuity amounts on authorized transactions before settlement.

What You Learn

How to submit tip adjustments using the legacy Adjust endpoint
When to use amount versus percentage adjustments
Expected payload format with decimal percentages
How tip adjustments interact with surcharge calculations

Overview

Tip adjustments let you update the gratuity on a preauthorized transaction after the customer signs the receipt. The /v1/payments/{transaction_id}/adjust endpoint supports two modes:

Mode	Fields	Description
Fixed amount	`type = "amount"` + `amount`	Adds or subtracts a specific amount in minor units
Percentage	`type = "percentage"` + `percentage`	Applies a percentage to the authorized subtotal

Prefer capture breakdowns: When possible, include the final tip in your capture request. Use tip adjustments only if the processor requires a separate adjustment step.

Request Example (percentage)

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

{
  "type": "percentage",
  "percentage": 0.18,
  "event_id": "tip-adjust-18"
}

Request Example (amount)

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

{
  "type": "amount",
  "amount": 1200,
  "event_id": "tip-adjust-amount-1200"
}

Notes

percentage is a decimal (e.g., 0.18 for 18%).
amount is provided in minor units (e.g., cents).
The endpoint returns the updated Transaction object with the revised tip.
If surcharges are configured, Koard recalculates surcharge amounts using the updated tip before settlement.

Related Guides

Capture – Preferred way to finalize tip and tax data
Incremental Auth – Increase the hold before adjusting tips
Payment Lifecycle – Understand where tip adjustments occur in the overall process