> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ionicfi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# The Terminal object

> What a Terminal is, its three independent states, and how it relates to Locations and provisioning.

A Terminal is Ionic's record of one card-present payment device at a
Location. Its ID starts with `tmr_` and belongs to exactly one Merchant and
mode. A Terminal accepts payments through
`POST /terminals/{id}/process_payment_intent`; the same call works for a
simulated Terminal and a physical one.

## Related objects

| Object               | ID prefix | What it represents                              |
| -------------------- | --------- | ----------------------------------------------- |
| Location             | `loc_`    | The business location where Terminals operate.  |
| Terminal             | `tmr_`    | One payment device, simulated or physical.      |
| Provisioning request | `tprov_`  | The workflow that delivers a physical Terminal. |
| Terminal Payment     | `tpr_`    | One card-present payment attempt on a Terminal. |

Every Terminal belongs to a Location. A Merchant can operate many Terminals
across many Locations; each Terminal processes one payment at a time.

## Three independent states

A Terminal reports three states that answer different questions. They change
independently, so read the one that matches your question.

| Field               | Question it answers                | Values                                                                        |
| ------------------- | ---------------------------------- | ----------------------------------------------------------------------------- |
| `status`            | Is the Terminal set up and usable? | `provisioning`, `requires_action`, `ready`, `disabled`, `replacing`, `failed` |
| `connection_status` | Can Ionic reach it right now?      | `online`, `offline`, `unknown`                                                |
| `capabilities`      | Which tenders can it accept?       | Map of capability name to `support` and `status`                              |

### Status

`status` tracks setup, not reachability. During physical Terminal provisioning,
the provisioning request moves through its own lifecycle and exposes a
`terminal_id` only when it becomes `ready`; the resulting Terminal is then
available as `ready`. A simulated Terminal is also created `ready`. Do not use
Terminal status to infer the state of an unfinished provisioning request.
Payments require `ready`; a payment sent to a Terminal in any other status
fails without reaching the device.

### Connection status

`connection_status` reports observed reachability, together with
`connection_observed_at` and `connection_status_stale`. A `ready` Terminal
can be `offline`: the device is set up correctly but unplugged or off the
store network. When the last observation is too old to trust, Ionic reports
`connection_status` as `unknown` and sets `connection_status_stale` to
`true`; `connection_observed_at` preserves when the last real observation
happened.

### Capabilities

`capabilities` maps each tender, such as `credit` or `debit_pin`, to two values:
`support` states whether the capability can be offered at all, while `status`
states whether it is operationally ready now. A `conditional` support value
means availability depends on the Merchant, device, payment setup, or
approval. A payment that selects `payment_type: debit` requires the Terminal's
`debit_pin` capability to be `ready`, independently of its setup and connection
states.

## Simulated and physical Terminals

Both kinds are the same object with the same fields and the same payment
call.

|                  | Simulated                                | Physical                                                       |
| ---------------- | ---------------------------------------- | -------------------------------------------------------------- |
| Created by       | `POST /terminals` with `type: simulated` | The Terminal provisioning workflow                             |
| Mode             | Test only                                | Test or live                                                   |
| Initial `status` | `ready`                                  | `ready` when the provisioning request assigns a `terminal_id`  |
| Device identity  | Synthetic model and serial               | Physical hardware; responses expose `serial_number_last4` only |

A simulated Terminal is durable: create it once, store the `tmr_…`, and
reuse it across test runs. Use it with
[Terminal payment scenarios](/guides/in-person-payments#test-without-physical-hardware)
to configure deterministic payment outcomes.

A physical Terminal arrives through a provisioning request. Create the
request at a Location, then retrieve it until `status` is `ready`; its
`terminal_id` then references the new Terminal. Ionic manages fulfillment,
and `required_actions` lists anything Ionic needs from you to continue.

## Identifiers

Send only Ionic IDs. Requests never identify a Terminal by a hardware serial
number, device credential, or another external device identifier. Ionic
manages device identity so a Terminal can keep its `tmr_…` across hardware
replacement.