# Terminal Management

Use the Terminal Management API to provision and manage terminals that are used to create payments and receive terminal-scoped configuration such as webhooks and enablement settings.

A terminal belongs to a location and merchant and is typically the final provisioning step before payment traffic begins.

#### What you can do

* Create terminals under the correct merchant and location
* Retrieve terminal details for configuration and troubleshooting
* Update terminal settings and webhook configuration
* Disable or delete terminals that should no longer process payments
* Use terminal identifiers in Payments, Reporting, and Settlement workflows

#### Life-cycle at a glance

* **Create:** `POST /Terminals`
* **Read:** `GET /Terminals/{id}`
* **Update:** `PUT /Terminals/{id}`
* **Disable:** `PUT /Terminals/{id}` with `isEnabled=false`
* **Delete:** `DELETE /Terminals/{id}`

#### Common terminal attributes

Typical terminal records include values such as:

* `id`
* `merchantId`
* `locationId`
* `name`
* `isEnabled`
* webhook configuration fields
* created and updated timestamps

Refer to the endpoint-specific schemas and examples for the exact request and response models supported in your environment.

#### Typical workflow

1. Create or identify the parent merchant and location.
2. Create a terminal under the correct location.
3. Save the returned `terminalId`.
4. Configure webhook behavior if your integration uses event notifications.
5. Use the `terminalId` when creating payments.
6. Update, disable, or delete the terminal as your deployment changes over time.

#### Create a terminal

Create a terminal after the merchant and location are available.

```http
POST /Terminals
```

Use the returned terminal record and save the `id` for downstream payment and administration workflows.

#### Get a terminal

Retrieve a terminal when you need to inspect configuration, confirm status, or troubleshoot behavior.

```http
GET /Terminals/{id}
```

#### Update a terminal

Use `PUT`, not `PATCH`, when updating a terminal.

```http
PUT /Terminals/{id}
```

If you are updating a terminal record, send the fields required by the current endpoint contract and examples for this path.

#### Disable a terminal

To disable a terminal without deleting it, update the terminal using `PUT /Terminals/{id}` and set `isEnabled=false` in the request body where supported by the endpoint model.

```http
PUT /Terminals/{id}
```

This is useful when you want to stop new payment activity while preserving the terminal record for audit, reporting, or later reactivation.

#### Delete a terminal

Delete a terminal only when you no longer need the record for operational use.

```http
DELETE /Terminals/{id}
```

Before deleting a terminal, confirm it is not still referenced by active workflows or deployment tooling.

#### Webhooks and terminal configuration

Terminal records may include webhook-related configuration used to route payment status events to your systems.

When using terminal-level webhook configuration:

* confirm the endpoint is reachable and monitored
* validate event handling in sandbox before production rollout
* design your webhook consumer to process retries safely and idempotently

#### Operational guidance

* Keep a clear mapping between partner, merchant, location, and terminal records.
* Treat terminal changes as production-impacting configuration updates.
* Prefer disabling a terminal before deleting it when you may need to preserve operational continuity or investigate prior activity.
* Store terminal identifiers in your internal systems so payments and support workflows can reference them consistently.

#### Related APIs

Terminal Management works closely with:

* **Merchant Management** for parent merchant records
* **Location Management** for parent location records
* **Payments** for payment creation using `terminalId`
* **Reporting** and **Settlement** for downstream operational visibility

#### Troubleshooting

* **Terminal not found**\
  Confirm the `id` is correct and belongs to the expected environment.
* **Update method rejected**\
  Use `PUT /Terminals/{id}` for updates. Do not use `PATCH /Terminals/{id}`.
* **Terminal cannot be used for payments**\
  Confirm the terminal is enabled, correctly associated to the expected merchant and location, and referenced with the correct `terminalId` in the payment request.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.bead.xyz/entity-management/terminal-management.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.