Offline Terminal Behaviour and Queued Transactions

Feature	Online	Offline
Card payment (tap/chip/PIN)	Yes	No
Display invoice/amount	Yes	Limited (last pushed)
Receipt printing	Yes	No (for new sales)
Terminal status check	Yes	No
Cash recording (app-side)	Yes	Yes (your app, not terminal)

The Paystack Terminal is a cloud-connected device. Every card authorization goes through the payment network in real time. There is no offline authorization mode.

// Poll terminal status before pushing a payment
async function checkTerminalStatus(terminalId) {
  var response = await fetch(
    'https://api.paystack.co/terminal/' + terminalId,
    { headers: { Authorization: 'Bearer ' + process.env.PAYSTACK_SECRET_KEY } }
  );
  var data = await response.json();
  // data.data.status: 'active' | 'inactive'
  return data.data?.status === 'active';
}

// In your POS checkout flow
async function processPayment(terminalId, amount) {
  var online = await checkTerminalStatus(terminalId);

  if (!online) {
    // Offer fallback
    return { error: 'Terminal offline', fallback: 'cash' };
  }

  // Push to terminal
  return pushToTerminal(terminalId, amount);
}

// Your POS app should also watch for network connectivity
window.addEventListener('offline', () => {
  showAlert('Network disconnected. Payment terminal unavailable. Accept cash or wait for reconnection.');
});

window.addEventListener('online', () => {
  hideAlert();
  recheckTerminalStatus();
});

Practical patterns for connectivity-resilient POS systems:

• Dual connectivity: Connect the terminal to both Wi-Fi and a 4G SIM. Most Paystack Terminal devices support SIM cards. When Wi-Fi drops, the SIM activates automatically.
• Cash fallback UI: Add a "Record cash payment" button that logs the sale locally without needing terminal connectivity. Sync to your backend when online.
• Status indicator: Show a green/red dot in your POS UI reflecting terminal status. Poll GET /terminal/:id every 30 seconds during active sessions.
• In-flight timeout handling: When you push a payment and the terminal goes offline mid-transaction, poll GET /terminal/:id/event for the action_id to check completion. Set a 60-second timeout before showing a "retry or use cash" prompt.

// Polling for in-flight terminal action
async function pollTerminalAction(terminalId, actionId, maxAttempts = 12) {
  for (var i = 0; i < maxAttempts; i++) {
    var response = await fetch(
      'https://api.paystack.co/terminal/' + terminalId + '/event/' + actionId,
      { headers: { Authorization: 'Bearer ' + process.env.PAYSTACK_SECRET_KEY } }
    );
    var data = await response.json();

    if (data.data?.status === 'success') return { paid: true };
    if (data.data?.status === 'failed' || data.data?.status === 'timeout') return { paid: false };

    await new Promise(r => setTimeout(r, 5000)); // wait 5s between polls
  }
  return { paid: false, error: 'timeout' };
}

This guide is part of the Paystack Terminal guide series.

Sign up for the McTaba newsletter