Overview

VINR in-person payments bring together three complementary layers: the Terminal API (available in both cloud-managed and local network modes), Tap to Pay for software-only acceptance on compatible mobile devices, and pre-built POS integrations for common point-of-sale systems. All three share the same payment object model and produce the same payment.completed webhook events as your online integrations — you do not need a separate data pipeline or reconciliation flow for in-person volume.

Solution typesAskCopy

How it connects to your backendAskCopy

Your backend asks VINR to collect a payment; the terminal handles the card interaction; VINR delivers the result as a standard webhook. The same payment object you work with online is what arrives in your system.

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

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

const session = await vinr.terminal.sessions.create({
  amount: 2500,
  currency: 'EUR',
  terminalId: 'term_8Rv3x...',
  description: 'Table 12 — lunch',
  metadata: { tableId: '12', serverId: 'emp_44' },
});

// session.id     → "ts_9Zp7k..."
// session.status → "pending"

curl -X POST https://api.vinr.com/v1/terminal/sessions \
  -H "X-Api-Key: $VINR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2500,
    "currency": "EUR",
    "terminalId": "term_8Rv3x...",
    "description": "Table 12 — lunch"
  }'

app.post('/webhooks/vinr', (req, res) => {
  const event = vinr.webhooks.constructEvent(
    req.body,
    req.headers['vinr-signature'] as string,
    process.env.VINR_WEBHOOK_SECRET!,
  );

  if (event.type === 'payment.completed') {
    const payment = event.data;
    console.log('Collected', payment.amount, payment.currency, 'on terminal', payment.terminalId);
  }

  res.sendStatus(200);
});

What's supportedAskCopy

Every VINR terminal supports the following acceptance capabilities out of the box. Feature availability can depend on your acquiring agreement and the market in which the device is deployed.

• Chip + PIN — EMV contact card with cardholder PIN entry
• Contactless / NFC — tap-to-pay for cards and mobile wallets up to the issuer's contactless limit
• Magnetic stripe — fallback swipe acceptance where regulations permit
• Apple Pay and Google Pay — in-store NFC wallet payments treated as contactless EMV tokens
• Tipping — percentage or fixed tip amounts presented on the terminal screen before authorization
• Surcharging — automatic card-type-based surcharge calculation (see Surcharging for legal requirements)
• Dynamic Currency Conversion (DCC) — offer foreign cardholders the option to pay in their home currency
• Cashback — dispense cash on debit transactions where the acquirer and jurisdiction allow
• MOTO — Mail Order / Telephone Order key-entry for card-not-present transactions processed through a terminal
• Offline authorization — store-and-forward for transactions taken during connectivity loss, subject to floor-limit rules
• Gift cards — closed-loop gift card redemption via the VINR Gift Card module
• Installments — split a purchase into equal installments at the point of sale where the issuer supports it

Before you startAskCopy

To accept your first in-person payment you need a provisioned terminal and a decision on which Terminal API mode fits your architecture.

• Hardware — review the full device specifications, supported markets, and ordering process in Terminal hardware.
• API mode — choose between cloud mode (VINR routes sessions to the device over the internet) and local mode (your server communicates with the terminal directly on the local network) in Terminal architecture.

Next stepsAskCopy