# Tipping

> Let customers add a gratuity at the terminal before the payment is captured.

Tipping presents a gratuity prompt to the customer after the sale amount is confirmed and before the card is presented. The customer selects a percentage, enters a custom amount, or skips. VINR captures the tip as part of the same authorisation — no separate capture step is required.

## Enable tipping

Tipping must be enabled at account level before it appears on terminals:

1. Go to **Dashboard → Settings → Payment processing → Tipping**.
2. Toggle **Enable tipping** on.
3. Set default percentage presets (optional — can be overridden per terminal or per API call).

To enable for a specific terminal only, go to **Dashboard → Hardware → Terminals → \[device] → Tipping**.

## Pass tip config in the API

```typescript
import { Vinr } from '@vinr/sdk';

const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

const terminalPayment = await vinr.terminal.payments.create({
  terminalId: 'term_01HZ5QXYZ',
  amount: 4500,
  currency: 'USD',
  reference: 'order_1042',
  tipConfig: {
    mode: 'percentage',
    percentages: [15, 18, 20],
    allowCustom: true,
    minimumAmount: 500,
  },
});
```

## Tip modes

## tipConfig parameters

## Reading the tip on the response

After the customer completes the card interaction, the terminal payment object includes:

```typescript
const completed = event.data.object;

console.log(completed.amount);        // base amount: 4500
console.log(completed.tipAmount);     // tip selected: 810 (18%)
console.log(completed.total);         // base + tip: 5310
console.log(completed.amountCaptured); // same as total for automatic capture
```

`tipAmount` is `0` if the customer skips the tip prompt.

## Manual capture (tip-on-receipt / post-authorisation adjustment)

For table-service restaurants where the tip is written on a paper receipt after the meal, use `captureMethod: "manual"` and `tipConfig.mode: "on_receipt"`. This authorises the base amount, and you adjust it upward when capturing.

```typescript
// 1. Create with manual capture
const tp = await vinr.terminal.payments.create({
  terminalId: 'term_01HZ5QXYZ',
  amount: 4500,
  currency: 'USD',
  reference: 'table_12',
  captureMethod: 'manual',
  tipConfig: { mode: 'on_receipt' },
});

// 2. Customer signs the receipt and writes in a tip
// 3. Staff enters the tip amount and calls capture
await vinr.terminal.payments.capture(tp.id, {
  amount: 5310, // base 4500 + tip 810
});
```

The capture amount may exceed the authorised amount by up to **20%** (or the card scheme maximum for your market, whichever is lower) without requiring a new authorisation.

> Uncaptured authorisations expire after **7 days**. If you do not capture within 7 days, the authorisation is released and the payment object transitions to `expired`. Always capture within the same business day for best interchange rates.

## Standalone terminals

Tipping on standalone terminals is configured in **Dashboard → Hardware → Terminals → \[device] → Tipping**. The same `mode`, `percentages`, and `minimumAmount` settings apply. No API call is needed — the configuration is pushed to the device automatically.

## Next steps

[Capture modes](/docs/payments/in-person/accept-a-payment#capture-modes) — Automatic vs manual capture — how to adjust the amount at capture time.

[Surcharging](/docs/payments/in-person/surcharge) — Apply a card-type surcharge before the tip prompt.

[All features](/docs/payments/in-person/features) — Overview of all optional terminal features.