Tipping

Tipping is part of the normal in-person authorization flow. The terminal shows the configured choices, the customer selects a tip, and kepa authorizes the subtotal plus tip as one total. Every payment read then returns the subtotal, tip, and total separately.

Configure the terminal prompt

Each merchant terminal configuration supports:

• tipEnabled — turns the customer prompt on or off.
• tipPresetBasisPoints — percentage choices; 1500, 1800, and 2000 mean 15%, 18%, and 20%.
• tipAllowCustomAmount — lets the customer enter another amount.
• tipPostAuthAdjustEnabled — permits the restaurant-style prompt after a base authorization only when the merchant's configured processor supports adjustment.
• tipFixedAmountMinor and tipFixedAmountThresholdMinor — offers a fixed tip only when the subtotal is at or below the threshold. The default offers $1.00 on subtotals up to $10.00 for a two-decimal currency.

Your kepa platform configuration writes these settings through PUT /v1/staff/merchants/{id}/terminal-tip-config. The terminal then downloads the resulting configuration from GET /api/v1/config/terminal during provisioning or config sync.

Authorize the final total

{
  "amount": 1180,
  "baseAmountMinor": 1000,
  "tipAmountMinor": 180,
  "tipSource": "preset:1800",
  "currencyCode": "USD",
  "transactionType": "purchase"
}

amount is always the total sent to the issuer. When a breakdown is supplied, baseAmountMinor + tipAmountMinor must equal amount. Invalid breakdowns fail before authorization; a tip is never silently discarded.

Read the retained breakdown

{
  "amountMinor": 1180,
  "baseAmountMinor": 1000,
  "tipAmountMinor": 180,
  "tipSource": "preset:1800"
}

The same fields are present on authorization responses, payment reads, and payment events. tipSource identifies a preset, fixed suggestion, custom amount, or no-tip choice without changing the money values.

Pre-authorization versus tip adjustment

For counter-service payments, collect the tip before authorization using the flow above. A contactless cryptogram includes the amount, so the terminal cannot change that amount after a tap and call it the same authorization.

Restaurant-style delayed tipping uses an open authorization:

1. Authorize the base amount using manual capture.
2. Call POST /api/v1/terminal/payments/{id}/tip-adjust with a stable idempotency key.
3. After the adjusted payment is returned, capture its new amountMinor.

Tip adjustment is processor-backed and fails closed when the configured acquirer does not advertise the capability. Capture cannot run while an adjustment has an unknown outcome, and it can never exceed the successfully adjusted authorization. See Take an in-person payment for the standard terminal flow.