Smart POS Terminal Integration Guide

This guide is designed for External POS Providers, Terminal Aggregators, and Hardware Vendors (including Paystack, Interswitch, Opay, Moniepoint, Kuda, PalmPay, and Nomba) who want to build applications and payment integrations on top of the Tracepos retail and accounting engine.

Architecture Overview

Tracepos acts as the central fiscal brain, multi-branch inventory tracker, and double-entry ledger. External Smart POS terminals (Android devices such as PAX, Sunmi, Telpo, Castles, and MoreFun) communicate with Tracepos to retrieve catalog items, process payments, and record auditable sales.

+-----------------------------------------------------------------------------------+
|                        EXTERNAL POS TERMINAL DEVICE                               |
|        (Paystack / Interswitch / Opay / Moniepoint / Kuda / PalmPay)              |
+-----------------------------------------------------------------------------------+
       |                                                                  |
       | 1. GET /products (Fetch SKU, Barcodes, Prices)                   | 3. Payment Processing
       v                                                                  |    (Card Tap / Transfer / USSD)
+-----------------------------------------------------+                   v
|                 Tracepos Engine                     |       +-----------------------+
|  - Real-Time Multi-Warehouse Inventory             |       | Bank / Switch Network |
|  - FIFO Batch Deductions                            |       | (Interswitch / NIBSS) |
|  - Balanced Journal Entries (Debit Cash, Credit Rev)|       +-----------------------+
|  - Invoice Generation & Customer Ledger             |                   |
+-----------------------------------------------------+                   |
       ^                                                                  |
       | 4. POST /sales (Submit Order + Itemized Breakdown + Auth Code)  |
       +------------------------------------------------------------------+

3 Core Integration Topologies

The Android POS terminal runs your custom application:

  1. Catalog Sync: Terminal downloads products via GET /products?limit=500 (or scans barcodes in real-time).
  2. Cart Building: Cashier rings up items or uses built-in barcode scanner.
  3. Card/Transfer Payment: Terminal software triggers the local EMV kernel or payment gateway to capture customer card or bank transfer.
  4. Order Commit: Upon successful payment confirmation, the terminal calls POST /sales with product_items and all_payments.
  5. Fiscal Receipt: Tracepos returns the official invoice_number and fiscal total, which the terminal prints on its thermal printer.

Topology 2: Cloud-Initiated Terminal-as-a-Service (TaaS)

The cashier operates on Tracepos desktop or tablet POS, while the customer pays on a standalone countertop terminal:

  1. Cashier chooses "Pay with POS Terminal" in Tracepos.
  2. Tracepos sends an initiation request to the provider's API (e.g. Kuda Business API, Interswitch Till API, Paystack Terminal API).
  3. The customer taps their card on the terminal.
  4. The terminal provider notifies Tracepos via webhook or callback.
  5. Tracepos automatically sets order payment_status to paid and prints the invoice.

Topology 3: End-of-Day Settlement & Reconciliation

Terminal providers send batch transaction files or webhooks at midnight. Tracepos automatically matches payment references against outstanding receivables using POST /payments.

Step-by-Step Implementation

Step 1: Configure Terminal Credentials

Each terminal device or store lane must be provisioned with its warehouse credentials:

TRACEPOS_BASE_URL=https://app.tracepos.net/api/v1/public
TRACEPOS_PUBLIC_KEY=Trp-pk-terminal-lane-01-xxxx
TRACEPOS_SECRET_KEY=Trp-sk-terminal-lane-01-yyyy

Step 2: Fetch Products & Barcodes

curl -X GET "https://app.tracepos.net/api/v1/public/products?limit=100" \
  -H "X-Tracepos-Public-Key: Trp-pk-YOUR_PUBLIC_KEY" \
  -H "X-Tracepos-Secret-Key: Trp-sk-YOUR_SECRET_KEY" \
  -H "Accept: application/json"

Response

{
  "status": "success",
  "data": {
    "data": [
      {
        "xid": "w8vBqGZ0",
        "name": "Coca-Cola 500ml",
        "item_code": "5449000000996",
        "sales_price": 500.00,
        "current_stock": 250
      }
    ]
  }
}

Step 3: Record Completed Sale & Payment

Once the card or transfer has been approved on the terminal, send the completed order to Tracepos:

curl -X POST "https://app.tracepos.net/api/v1/public/sales" \
  -H "X-Tracepos-Public-Key: Trp-pk-YOUR_PUBLIC_KEY" \
  -H "X-Tracepos-Secret-Key: Trp-sk-YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: TERM-01-20260930-994812" \
  -d '{
    "user_id": "WalkinCustomer",
    "order_date": "2026-09-30 17:30:00",
    "invoice_number": "INV-TERM01-994812",
    "product_items": [
      {
        "xid": "w8vBqGZ0",
        "quantity": 2,
        "unit_price": 500.00
      }
    ],
    "subtotal": 1000.00,
    "total": 1000.00,
    "discount": 0.00,
    "tax_amount": 0.00,
    "all_payments": [
      {
        "amount": 1000.00,
        "payment_mode_id": "POS_CARD",
        "reference": "STAN-884920-RRN-993829104",
        "notes": "Opay POS Terminal #OP-449102"
      }
    ]
  }'

Response

{
  "status": "success",
  "order_id": 48291,
  "invoice_number": "INV-TERM01-994812",
  "total_amount": 1000.00
}

Provider-Specific Recommendations

1. Paystack Terminal Integrations

  • Use the Paystack Terminal API to push charges directly to Paystack Android POS hardware.
  • Listen for Paystack webhooks charge.success to match against Tracepos payment modes.
  • Pass the Paystack reference into all_payments[0].reference for audit matching.

2. Interswitch SmartPOS & Till

  • Interswitch provides Till APIs (/socket or Paymate API).
  • Store interswitch_terminal_id and interswitch_access_key in Tracepos payment mode settings.
  • Send the tillRef generated by Tracepos into the Interswitch POS prompt.

3. Opay & Moniepoint Smart POS

  • For merchants operating high-volume supermarket counters on Opay or Moniepoint devices:
    • Install a lightweight native Android client that runs on the POS hardware.
    • Scan product barcodes with the built-in camera or laser imager.
    • Process the card transaction via the local EMV app SDK.
    • Push the combined basket + payment to Tracepos POST /sales.

4. Kuda Business POS

  • Tracepos has native support for Kuda Business Sell Tokens and Terminal Serials.
  • Authenticates securely via Kuda Partner APIs and reconciles settlements automatically.

Offline-Resilience & Edge Buffering

In regions with intermittent cellular coverage:

  1. Local SQLite Queue: Store pending sales locally on the terminal when offline.
  2. Deterministic References: Generate a unique invoice number on the terminal (INV-{TERMINAL_ID}-{TIMESTAMP}).
  3. Background Auto-Drain: When connectivity resumes, the terminal drains the queue to POST /sales sequentially.
  4. Idempotency Protection: Tracepos ensures that retried offline orders are never duplicated.