Authenticated API

This endpoint requires a valid JWT Bearer token with integration_admin or manager roles. Accessible via the API gateway at /v1/integrations/*.

POS Hardware API

Manage POS terminals, card readers, receipt printers, cash drawers, and other peripheral devices.

Overview

Attribute	Value
Base Path	`/api/v1/hardware`
Authentication	Bearer Token
Required Roles	`manager`, `restaurant_manager`, `pos_staff`, `server`, `kitchen`, `dispatcher`, `tenant_admin`, `platform_admin`, `system_admin`, `super_admin`

Supported Hardware

Card Readers

Manufacturer	Models	Features
Stripe	M2, S700	Tap, Chip, Swipe
Square	Reader, Terminal	Tap, Chip, Swipe
Verifone	P400, V400m	Full payment terminal
Ingenico	Lane 3000	Full payment terminal
PAX	A920, A80	Android-based terminal

Printers

Manufacturer	Models	Type
Epson	TM-T88VI, TM-m30II	Thermal receipt
Star Micronics	TSP143IV, mC-Print3	Thermal receipt
Bixolon	SRP-350plusIII	Thermal receipt
Brother	QL-820NWB	Label printer

Accessories

Type	Supported Models
Cash Drawers	APG, MMF, Star
Barcode Scanners	Zebra, Honeywell, Socket Mobile
Customer Displays	Logic Controls, Partner Tech
Scales	CAS, Avery Berkel

Devices

List Devices

GET /api/v1/hardware/devices

Query Parameters

Parameter	Type	Description
`location_id`	uuid	Filter by location
`type`	string	`card_reader`, `printer`, `cash_drawer`, `scanner`
`status`	string	`online`, `offline`, `error`

Response

{
  "devices": [
    {
      "id": "dev_001",
      "type": "card_reader",
      "manufacturer": "stripe",
      "model": "BBPOS WisePOS E",
      "serial_number": "STRM2-12345678",
      "name": "Register 1 Card Reader",
      "location_id": "loc_123",
      "station": "register_1",
      "status": "online",
      "battery": {
        "level": 85,
        "charging": false
      },
      "firmware": {
        "version": "2.5.1",
        "update_available": false
      },
      "last_seen": "2026-01-24T19:30:00Z",
      "connection": {
        "type": "bluetooth",
        "signal_strength": "strong"
      }
    },
    {
      "id": "dev_002",
      "type": "printer",
      "manufacturer": "epson",
      "model": "TM-T88VI",
      "serial_number": "EPS88-87654321",
      "name": "Kitchen Printer",
      "location_id": "loc_123",
      "station": "kitchen",
      "status": "online",
      "supplies": {
        "paper_level": "ok",
        "estimated_prints_remaining": 500
      },
      "last_seen": "2026-01-24T19:30:00Z",
      "connection": {
        "type": "network",
        "ip_address": "192.168.1.50"
      }
    },
    {
      "id": "dev_003",
      "type": "cash_drawer",
      "manufacturer": "apg",
      "model": "Series 4000",
      "serial_number": "APG4K-11223344",
      "name": "Register 1 Cash Drawer",
      "location_id": "loc_123",
      "station": "register_1",
      "status": "closed",
      "last_opened": "2026-01-24T19:15:00Z",
      "connection": {
        "type": "printer_driven",
        "connected_to": "dev_004"
      }
    }
  ],
  "summary": {
    "total": 12,
    "online": 11,
    "offline": 1,
    "error": 0
  }
}

Register Device

POST /api/v1/hardware/devices

Request Body

{
  "type": "card_reader",
  "manufacturer": "stripe",
  "registration_code": "sepia-cerulean-ocelot",
  "name": "Register 2 Card Reader",
  "location_id": "loc_123",
  "station": "register_2",
  "settings": {
    "auto_reconnect": true,
    "timeout_seconds": 120
  }
}

Response

{
  "id": "dev_005",
  "type": "card_reader",
  "manufacturer": "stripe",
  "model": "BBPOS WisePOS E",
  "serial_number": "STRM2-99887766",
  "name": "Register 2 Card Reader",
  "status": "online",
  "registered_at": "2026-01-24T19:35:00Z"
}

Get Device

GET /api/v1/hardware/devices/{device_id}

Response

{
  "id": "dev_001",
  "type": "card_reader",
  "manufacturer": "stripe",
  "model": "BBPOS WisePOS E",
  "serial_number": "STRM2-12345678",
  "name": "Register 1 Card Reader",
  "location_id": "loc_123",
  "station": "register_1",
  "status": "online",
  "capabilities": [
    "tap",
    "chip",
    "swipe",
    "manual_entry",
    "apple_pay",
    "google_pay"
  ],
  "battery": {
    "level": 85,
    "charging": false,
    "estimated_hours_remaining": 8
  },
  "firmware": {
    "version": "2.5.1",
    "update_available": false,
    "last_updated": "2026-01-15T00:00:00Z"
  },
  "connection": {
    "type": "bluetooth",
    "paired_device": "iPad Pro (Register 1)",
    "signal_strength": "strong",
    "connected_since": "2026-01-24T08:00:00Z"
  },
  "settings": {
    "auto_reconnect": true,
    "timeout_seconds": 120,
    "beep_on_success": true,
    "display_tips": true
  },
  "stats": {
    "transactions_today": 145,
    "transactions_total": 15420,
    "last_transaction": "2026-01-24T19:28:00Z"
  },
  "registered_at": "2025-06-15T00:00:00Z",
  "last_seen": "2026-01-24T19:30:00Z"
}

Update Device

PUT /api/v1/hardware/devices/{device_id}

Request Body

{
  "name": "Main Register Card Reader",
  "station": "register_main",
  "settings": {
    "timeout_seconds": 180,
    "display_tips": true
  }
}

Remove Device

DELETE /api/v1/hardware/devices/{device_id}

Card Reader Operations

Collect Payment

POST /api/v1/hardware/devices/{device_id}/collect-payment

Request Body

{
  "amount": 4550,
  "currency": "usd",
  "order_id": "ord_12345",
  "options": {
    "skip_tipping": false,
    "tip_eligible": true,
    "tip_options": [15, 18, 20, 25],
    "allow_custom_tip": true
  },
  "metadata": {
    "table": "12",
    "server": "emp_001"
  }
}

Response

{
  "collection_id": "coll_001",
  "status": "awaiting_input",
  "device_id": "dev_001",
  "amount": 4550,
  "display_message": "Insert, tap, or swipe card",
  "timeout_at": "2026-01-24T19:32:00Z"
}

Cancel Collection

POST /api/v1/hardware/devices/{device_id}/cancel-collection

Request Body

{
  "collection_id": "coll_001",
  "reason": "customer_cancelled"
}

Get Collection Status

GET /api/v1/hardware/devices/{device_id}/collections/{collection_id}

Response

{
  "collection_id": "coll_001",
  "status": "completed",
  "amount": 4550,
  "tip_amount": 910,
  "total_amount": 5460,
  "payment_method": {
    "type": "card_present",
    "brand": "visa",
    "last4": "4242",
    "exp_month": 12,
    "exp_year": 2028,
    "funding": "credit",
    "entry_method": "contactless"
  },
  "payment_intent_id": "pi_abc123",
  "receipt": {
    "id": "rcpt_001",
    "print_url": "/api/v1/hardware/receipts/rcpt_001/print"
  }
}

Set Reader Display

POST /api/v1/hardware/devices/{device_id}/display

Request Body

{
  "type": "cart",
  "cart": {
    "line_items": [
      {"description": "Ribeye Steak", "quantity": 1, "amount": 3500},
      {"description": "Caesar Salad", "quantity": 1, "amount": 1050}
    ],
    "subtotal": 4550,
    "tax": 365,
    "total": 4915
  }
}

Clear Reader Display

POST /api/v1/hardware/devices/{device_id}/clear-display

Printer Operations

Print Receipt

POST /api/v1/hardware/devices/{device_id}/print

Request Body

{
  "template": "receipt",
  "data": {
    "order_id": "ord_12345",
    "location_name": "Downtown Restaurant",
    "address": "123 Main St, City, ST 12345",
    "date": "2026-01-24",
    "time": "19:30",
    "server": "Sarah",
    "table": "12",
    "items": [
      {"name": "Ribeye Steak", "qty": 1, "price": 35.00},
      {"name": "Caesar Salad", "qty": 1, "price": 10.50}
    ],
    "subtotal": 45.50,
    "tax": 3.65,
    "tip": 9.10,
    "total": 58.25,
    "payment_method": "Visa ****4242",
    "footer": "Thank you for dining with us!"
  },
  "copies": 1
}

Response

{
  "print_job_id": "print_001",
  "status": "completed",
  "device_id": "dev_002",
  "copies_printed": 1,
  "printed_at": "2026-01-24T19:31:00Z"
}

Print Kitchen Ticket

POST /api/v1/hardware/devices/{device_id}/print

Request Body

{
  "template": "kitchen_ticket",
  "data": {
    "order_id": "ord_12345",
    "order_number": "42",
    "table": "12",
    "server": "Sarah",
    "time": "19:30",
    "items": [
      {
        "name": "Ribeye Steak",
        "qty": 1,
        "modifiers": ["Medium Rare", "No Onions"],
        "notes": "Allergy: Shellfish"
      },
      {
        "name": "Caesar Salad",
        "qty": 1,
        "modifiers": ["Dressing on Side"]
      }
    ],
    "special_instructions": "VIP Guest - Owner's friend",
    "priority": "rush"
  },
  "options": {
    "cut_after": true,
    "beep": true
  }
}

Open Cash Drawer

POST /api/v1/hardware/devices/{device_id}/open

Request Body

{
  "reason": "cash_payment",
  "order_id": "ord_12345",
  "employee_id": "emp_001"
}

Response

{
  "status": "opened",
  "opened_at": "2026-01-24T19:32:00Z",
  "logged": true
}

Get Drawer Status

GET /api/v1/hardware/devices/{device_id}/drawer-status

Response

{
  "device_id": "dev_003",
  "status": "closed",
  "last_opened": "2026-01-24T19:32:00Z",
  "opened_by": "emp_001",
  "reason": "cash_payment",
  "opens_today": 45
}

Device Management

Update Firmware

POST /api/v1/hardware/devices/{device_id}/firmware/update

Response

{
  "update_id": "update_001",
  "current_version": "2.5.0",
  "target_version": "2.5.1",
  "status": "downloading",
  "progress": 0,
  "estimated_duration_minutes": 10
}

Get Firmware Update Status

GET /api/v1/hardware/devices/{device_id}/firmware/status

Restart Device

POST /api/v1/hardware/devices/{device_id}/restart

Run Diagnostics

POST /api/v1/hardware/devices/{device_id}/diagnostics

Response

{
  "device_id": "dev_001",
  "diagnostics": {
    "battery": {
      "status": "healthy",
      "level": 85,
      "cycles": 150
    },
    "card_reader": {
      "tap": "operational",
      "chip": "operational",
      "swipe": "operational"
    },
    "display": {
      "status": "operational",
      "brightness": "auto"
    },
    "connectivity": {
      "bluetooth": "connected",
      "wifi": "not_configured",
      "signal_strength": -45
    },
    "storage": {
      "used_mb": 120,
      "total_mb": 512
    }
  },
  "overall_status": "healthy",
  "ran_at": "2026-01-24T19:33:00Z"
}

Printer Supplies

Get Supplies Status

GET /api/v1/hardware/devices/{device_id}/supplies

Response

{
  "device_id": "dev_002",
  "paper": {
    "status": "ok",
    "level_percent": 75,
    "estimated_prints_remaining": 500,
    "low_paper_threshold": 100
  },
  "last_paper_change": "2026-01-20T00:00:00Z",
  "print_head": {
    "status": "healthy",
    "total_prints": 125000
  }
}

Station Assignment

Assign Device to Station

POST /api/v1/hardware/stations/{station_id}/devices

Request Body

{
  "device_ids": ["dev_001", "dev_004", "dev_003"],
  "configuration": {
    "primary_card_reader": "dev_001",
    "receipt_printer": "dev_004",
    "cash_drawer": "dev_003"
  }
}

Get Station Devices

GET /api/v1/hardware/stations/{station_id}/devices

Webhooks

Event	Description
`hardware.device_online`	Device came online
`hardware.device_offline`	Device went offline
`hardware.device_error`	Device error occurred
`hardware.payment_collected`	Payment successfully collected
`hardware.payment_failed`	Payment collection failed
`hardware.drawer_opened`	Cash drawer opened
`hardware.paper_low`	Printer paper running low
`hardware.firmware_available`	Firmware update available

Error Responses

Status	Code	Description
400	`device_busy`	Device is processing another request
404	`device_not_found`	Device ID not found
408	`collection_timeout`	Payment collection timed out
409	`device_offline`	Device is not connected
422	`incompatible_device`	Device doesn't support operation
503	`printer_error`	Printer error (paper jam, etc.)

Payments API - Payment processing
Orders API - Order management
KDS API - Kitchen display integration

Overview​

Supported Hardware​

Card Readers​

Printers​

Accessories​

Devices​

List Devices​

Register Device​

Get Device​

Update Device​

Remove Device​

Card Reader Operations​

Collect Payment​

Cancel Collection​

Get Collection Status​

Set Reader Display​

Clear Reader Display​

Printer Operations​

Print Receipt​

Print Kitchen Ticket​

Open Cash Drawer​

Get Drawer Status​

Device Management​

Update Firmware​

Get Firmware Update Status​

Restart Device​

Run Diagnostics​

Printer Supplies​

Get Supplies Status​

Station Assignment​

Assign Device to Station​

Get Station Devices​

Webhooks​

Error Responses​

Related Documentation​

Overview

Supported Hardware

Card Readers

Printers

Accessories

Devices

List Devices

Register Device

Get Device

Update Device

Remove Device

Card Reader Operations

Collect Payment

Cancel Collection

Get Collection Status

Set Reader Display

Clear Reader Display

Printer Operations

Print Receipt

Print Kitchen Ticket

Open Cash Drawer

Get Drawer Status

Device Management

Update Firmware

Get Firmware Update Status

Restart Device

Run Diagnostics

Printer Supplies

Get Supplies Status

Station Assignment

Assign Device to Station

Get Station Devices

Webhooks

Error Responses

Related Documentation