Terminal Management

Terminal Management lets you create, configure, and retire the devices—physical or virtual—that initiate payments through Bead. Each terminal is represented by a unique terminalId, which you pass when you open a payment page or call other device-scoped APIs.

Life-cycle at a glance

Phase	Typical action	Key API calls
Provision	Create the terminal in the correct location.	POST /Terminals
Configure	Add metadata (name, description), set a device-level webhook, enable tender types.	PATCH / PUT /Terminals/{id} • PUT /Terminals/{id}/webhook
Operate	Use terminalId in payment flows; monitor status via webhooks or Reporting.	Any payment-initiation call • Reporting endpoints
Retire	Disable or delete the terminal when the device is scrapped or tests finish.	PATCH /Terminals/{id} (isEnabled=false) or DELETE /Terminals/{id}

Hierarchy recap

Partner
 └─ Merchant
    └─ Location
       └─ Terminal
          └─ Payment

• Partner – Your master account or ISV/VAR container.

• Merchant – A business entity that processes payments.

• Location – A physical store or logical site belonging to the merchant.

• Terminal – The individual device (or virtual endpoint) that initiates payments.

• Payment – A single transaction created by that terminal.

Why the extra “Location” layer? Many merchants operate multiple stores; grouping terminals by location simplifies reporting (e.g., end-of-day totals per store) and access control.

Available operations

Page	Description
Create Terminal	POST /Terminals – add a device to a location (pass locationId in the body).
List Terminals	GET /Locations/{locationId}/terminals – enumerate devices in one location.
Get Terminal	GET /Terminals/{id} – fetch full details for a device.
Update Terminal	PATCH or PUT /Terminals/{id} – modify metadata, tender types, enable/disable.
Delete Terminal	DELETE /Terminals/{id} – remove a device that is no longer needed.
Set / Delete Webhook	PUT / DELETE /Terminals/{id}/webhook – manage device-level callbacks.

All calls require an Authorization: Bearer <token> header.

Best practices

• Create under the right location – Pass the correct locationId when you call POST /Terminals so dashboards and reports roll up cleanly.

• PATCH vs. PUT – Use PATCH for small tweaks (e.g., toggling isEnabled) and PUT when you’re replacing all editable fields.

• Clean up test data – Delete test terminals after automated runs; disable production devices first, then delete once no active sessions exist.

• Webhooks

  • Terminal-level for small estates or per-device alerting.

  • Location- or merchant-level for high-volume estates where one URL per device is unmanageable.

Refer to the individual endpoint pages for request/response details, or check the Changelog for recent updates.