Tipping

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 tippingAskCopy

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 APIAskCopy

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 modesAskCopy

tipConfig parametersAskCopy

Reading the tip on the responseAskCopy

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

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)AskCopy

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.

// 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.

Standalone terminalsAskCopy

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 stepsAskCopy