Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.clear-box.io/llms.txt

Use this file to discover all available pages before exploring further.

Once a merchant is KYB-active, you model its physical footprint as locations (sites inside the venue) and terminals (the actual readers). Every authorization ClearBox sees can be traced back to a specific terminal at a specific location under a specific merchant.

​
Locations

A location is a physical or logical site under a merchant — a stage, a food court, a campus dining hall, a stadium concourse section. Locations carry an address and a timezone so transaction timestamps and reporting line up with the operator’s view.

​
Add a location

POST /v1/merchants/mer_7d3a/locations

{
  "name": "Main Stage",
  "address": {
    "line1": "1 Festival Way",
    "city": "Indio",
    "region": "CA",
    "postal_code": "92201",
    "country": "US"
  },
  "timezone": "America/Los_Angeles"
}

{
  "location_id": "loc_1e8f",
  "merchant_id": "mer_7d3a",
  "name": "Main Stage",
  "timezone": "America/Los_Angeles"
}

​
Terminals

A terminal is the actual hardware or software endpoint where a guest taps, scans, or pays. ClearBox supports several terminal types:
TypeDescription
pos_legacyAn existing legacy point-of-sale terminal that doesn’t natively speak blockchain. ClearBox bridges it.
rist_wristbandA RIST wristband scanner (RFID + ticketing + payment). Common in festivals and resorts.
mobile_readerA handheld card reader carried by staff (roving sales).
qr_kioskA QR-code kiosk where a guest scans to pay from their phone.

​
Register a terminal

POST /v1/merchants/mer_7d3a/terminals

{
  "location_id": "loc_1e8f",
  "type": "rist_wristband",
  "label": "Beer Garden Reader 3",
  "external_id": "RIST-BG-003"
}
The external_id is the ID of the terminal in the merchant’s existing system (RIST, Square, Toast, etc.). ClearBox uses it to match incoming authorizations from that system back to the right terminal. 
{
  "terminal_id": "trm_6a2c",
  "merchant_id": "mer_7d3a",
  "location_id": "loc_1e8f",
  "type": "rist_wristband",
  "label": "Beer Garden Reader 3",
  "external_id": "RIST-BG-003",
  "status": "active"
}

​
What you’ve built

You can now trace every settled transaction back to a merchant, a location within that merchant, and a specific terminal at that location. Reporting and reconciliation use this chain.

POS integrations

Bridge legacy POS networks (RIST, Square, Toast) into ClearBox.

Settlement & payouts

Configure where settled funds arrive.