Create Terminal

Overview Creates a new payment terminal under an existing location. Only name and locationId are required—other settings can be patched later.

Endpoint

POST /Terminals

Purpose

Register a device and return the credentials (login / password) it will use to process payments.

Request headers

Header	Value
Authorization	Bearer <access-token>
Content-Type	application/json
Accept	application/json

Request body

Field	Type	Required	Notes
name	string	✔︎	Friendly label shown in dashboards.
locationId	string	✔︎	The location that owns this terminal.
tenderTypes	array<string>	✘	If omitted, inherits the location defaults.
description	string	✘	Free-form description (POS lane, kiosk #, etc.).
displayLogo	boolean	✘	true shows your brand logo on device screens.

Example request

bashCopyEditcurl -X POST "https://api.test.devs.beadpay.io/Terminals" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Front Counter 1",
        "locationId": "loc_bfdc6a7f",
        "tenderTypes": ["ethereum"],
        "description": "Register 1 terminal",
        "displayLogo": true
      }'

Success response — 200

jsonCopyEdit{
  "login": "TERM-abc123",
  "password": "securePassword",
  "terminal": {
    "terminalId": "term123",
    "name": "Front Counter 1",
    "description": "Register 1 terminal",
    "merchantId": "mer_4e5a13aa",
    "merchantLocationId": "loc_bfdc6a7f",
    "displayLogo": true,
    "webhookUrl": "https://yourapp.com/webhooks",
    "isEnabled": true,
    "tenderTypes": ["ethereum"],
    "created": "2025-04-22T18:54:32.394Z",
    "updated": "2025-04-22T18:54:32.394Z"
  }
}

Field	Description
login, password	Credentials for device authentication (store securely—won’t be returned again).
terminal.terminalId	Use in every payment request and when patching or deleting the terminal.
isEnabled	false blocks transactions without deleting history.

Error responses

Code	Condition
400	Missing name or locationId, invalid tender type.
404	locationId not found or not owned by your org.
409	Duplicate terminal name under the same location.

Best practices

• Store three values after creation: terminalId, login, password.

• Idempotency-Key – Send one if you retry requests to avoid duplicates.

• Disable before delete – Prevents stray payments if the POS still holds credentials.

• Webhooks – Prefer merchant- or location-level webhooks; set terminal-level only when device-specific events are required.