Update Terminal

Modify a terminal’s metadata, tender types, or display options. Two verbs are supported:

Verb	When to use it	Body semantics
PUT	You want to replace the entire editable object—every mutable field must be present in the request. Fields you omit will be reset to their default values.	Full terminal object minus read-only fields (id, merchantId, created, etc.).
PATCH	You want to change only one or a few fields. Fields you omit remain unchanged.	Just the properties you want to update.

Endpoint

/Terminals/{id}

• PUT → https://api.test.devs.beadpay.io/Terminals/{id}

• PATCH → https://api.test.devs.beadpay.io/Terminals/{id}

Required header

Name	Example
Authorization	Bearer eyJhbGciOiJS…
Content-Type	application/json

Editable fields

Field	Type	PUT	PATCH	Notes
name	string	✔	✔	Friendly display name.
description	string	✔	✔	Optional notes shown in dashboards.
tenderTypes	array	✔	✔	Accepted methods (e.g., ethereum).
displayLogo	boolean	✔	✔	Show Bead logo on hosted pages.
isEnabled	boolean	✔	✔	Disable to block new payments.
(others read-only)		—	—	id, merchantId, created, updated, etc.

PUT example – full replace

curl -X PUT \
  "https://api.test.devs.beadpay.io/Terminals/12312313" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Front Counter POS",
    "description": "Main checkout terminal",
    "tenderTypes": ["ethereum"],
    "displayLogo": true,
    "isEnabled": true
}'

Successful 200 OK response (same schema as Get Terminal):

{
  "id": "12312313",
  "name": "Front Counter POS",
  "description": "Main checkout terminal",
  "merchantId": "mrc_7f4a2d3e4b",
  "merchantLocationId": "loc_c1a2eb",
  "displayLogo": true,
  "webhookUrl": "https://example.com/webhooks/terminal/12312313",
  "isEnabled": true,
  "tenderTypes": ["ethereum"],
  "created": "2025-04-24T23:00:45.148Z",
  "updated": "2025-04-24T23:15:29.611Z"
}

PATCH example – partial update

curl -X PATCH \
  "https://api.test.devs.beadpay.io/Terminals/12312313" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "isEnabled": false
}'

Only the isEnabled flag changes; all other fields remain intact.

Response codes

HTTP status	Meaning
200 OK	Update applied; full terminal object returned.
400 Bad Request	Body failed validation (e.g., missing fields on PUT).
404 Not Found	id does not match any terminal you own.
409 Conflict	Attempted to disable a terminal with active payment sessions.
401 / 403	Invalid or expired token.

Choosing PUT vs. PATCH

Scenario	Recommended verb
Admin screen where you save the entire form every time	PUT
Automation toggling isEnabled for maintenance windows	PATCH
Script that only updates tenderTypes after a new payment method rollout	PATCH
Migration syncing every editable field from an external system	PUT

Usage tips

• Use PATCH for CI scripts and quick toggles; it’s safer because you can’t accidentally reset untouched fields.

• Always read the response body—it echoes the updated object and includes the new updated timestamp.

• If you need to modify the terminal’s webhook URL, use Set Webhook; it has its own endpoint.