Offline payments

When a VINR terminal loses its network connection, offline mode allows it to continue accepting payments by approving transactions locally against cached BIN data and a configurable floor limit. Queued transactions are submitted for authorisation when connectivity is restored. This ensures checkout can continue during brief outages without turning customers away.

AvailabilityAskCopy

The CM30 requires a live host device connection and does not support standalone offline queuing.

Configure offline modeAskCopy

Per terminal (Dashboard)

Go to Dashboard → Hardware → Terminals → [device] → Advanced → Offline payments:

• Offline payments: Enabled / Disabled
• Floor limit: Maximum transaction amount that can be approved offline (in your settlement currency). The default is 0 (no offline approvals) until you explicitly set a limit.
• Max queued transactions: Maximum number of transactions to hold in the offline queue. Default: 50. Maximum: 200.
• Queue duration: Maximum age of a queued transaction before it is voided on reconnect. Default: 4 hours. Maximum: 24 hours.

Per transaction (API)

Override the terminal's offline setting for a single payment:

const terminalPayment = await vinr.terminal.payments.create({
  terminalId: 'term_01HZ5QXYZ',
  amount: 2000,
  currency: 'USD',
  reference: 'order_9901',
  offlineMode: 'allow',    // or 'deny' to force online-only for this payment
});

How offline authorization worksAskCopy

Webhook behaviour for offline transactionsAskCopy

Offline transactions go through an additional queued status before completing:

created → queued → processing → completed
                             ↘ failed (on sync failure)

Your webhook handler receives these events in order. The queued_at timestamp on the payment object reflects when the card was presented offline; completed_at reflects when the sync authorisation cleared.

if (event.type === 'terminal_payment.completed') {
  const tp = event.data.object;

  if (tp.offlineQueued) {
    // Transaction was queued offline
    const queueDuration = new Date(tp.completedAt).getTime()
      - new Date(tp.queuedAt).getTime();
    console.log(`Queued for ${queueDuration / 1000}s before sync`);
  }
}

When queued transactions fail on syncAskCopy

If an issuer declines a queued transaction on sync, you receive terminal_payment.failed with declineCode: "offline_sync_failure" and a nested syncDeclineCode explaining the underlying reason (insufficient_funds, lost_or_stolen, etc.).

The terminal has already dispensed goods and printed a receipt. You must handle the reversal in your own systems — VINR will not collect the funds.

if (event.type === 'terminal_payment.failed') {
  const tp = event.data.object;

  if (tp.declineCode === 'offline_sync_failure') {
    await recordOfflineChargeback({
      reference: tp.reference,
      amount: tp.amount,
      syncDeclineCode: tp.syncDeclineCode,
    });
  }
}

Setting an appropriate floor limitAskCopy

Your floor limit is the single most important control for managing offline risk. A higher floor limit means more transactions can be approved offline, but also more exposure if cards are declined on sync.

General guidance:

Review your chargeback history before raising floor limits. Discuss limits with your VINR account manager — they can provide BIN-level risk data for your specific card mix.

Next stepsAskCopy