The Terminal object - Ionic Docs

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. Every test account automatically receives three ready simulated Terminals across two Ionic test Locations. Their IDs are unique to the Account. The universal test_profile values—approved, declined, and delayed—identify their deterministic default behavior.

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.

Refund receipts

Whether a card-present Refund names a terminal_id, where it runs, and the Account’s automatic refund receipts setting decide how its receipt prints. terminal_id marks a refund done at the counter, so its receipt prints on that Terminal:

Refund	Automatic refund receipts on	Automatic refund receipts off
With `terminal_id`, runs without the card: a settled refund, or a same-day void without refunds on the Terminal	Prints automatically on that Terminal	Prints on request through the print route below
With `terminal_id`, runs on the Terminal: a same-day void with refunds on the Terminal, or a settled PIN-debit return	Prints as part of the refund	Prints as part of the refund
Without `terminal_id`, such as a refund from the Dashboard	Prints on request through the print route below	Prints on request through the print route below

Ionic turns on refunds on the Terminal only together with automatic refund receipts, so on those Accounts every card-present refund with terminal_id prints once with no print request. Use the print route for a refund without terminal_id, or for an additional copy; a request for a refund that already printed prints another copy. Request a receipt for a succeeded card-present Refund on any ready Terminal of the same Account and mode:

POST /v1/terminals/tmr_.../print
Authorization: Bearer sk_test_...
Idempotency-Key: refund-receipt-1
Content-Type: application/json

{"refund_id": "rf_..."}

Use a secret key with payments:write; platforms select authorized connected Accounts with Ionic-Account. The response reports status: "printed" when the Terminal confirms printing, or status: "failed" when it does not. Retrying with the same idempotency key replays that result. To request another print, use a new key. The API reference lists every field and error. Automatic refund receipts are off by default. Ionic staff can enable them for an Account separately in test and live mode. GET /v1/account reports this policy as refund_receipts.auto_print. When enabled, a card-present Refund that includes terminal_id requests a receipt on that Terminal after the Refund is saved; a Refund without terminal_id does not print on its own. Printing starts immediately in the background; the refund response does not wait for the printer and does not confirm that paper printed. The Dashboard also offers Print receipt for manual copies. Allow automatic printing to finish before requesting another copy. Printing briefly occupies the Terminal, and an interrupted print frees it within 30 seconds. A sale or manual print submitted while it is busy can return 409 TERMINAL_BUSY and sends nothing to the Terminal. Retry after the current operation finishes with a new idempotency key, because a repeated key returns the saved 409 response. If an automatic receipt finds the Terminal busy before sending the print, it waits and tries again. An offline Terminal may not print, and printing cannot change an approved Refund. Unconfirmed print attempts are not automatically retried, because paper may already have printed. Online refunds are unaffected. Refunds that run on the Terminal print there and do not request an additional automatic receipt.

Refunds on the Terminal

Ionic staff can turn on refunds on the Terminal for an Account, separately in test and live mode, together with automatic refund receipts. Then a full refund that includes terminal_id, made before the sale’s batch settles, voids the sale on the Terminal that took it. No card is needed, and the Terminal prints the receipt as part of the refund. Naming another Terminal returns 422 CHARGE_NOT_REFUNDABLE and sends nothing. A partial refund must wait until the batch settles; until then it returns 422. After the batch settles, a refund goes back to the original card, with or without terminal_id. With terminal_id, it prints automatically on that Terminal. A settled PIN-debit refund always needs terminal_id, because a PIN-debit refund needs the card. The customer presents the card on that Terminal, which prints the receipt. Send terminal_id only for refunds done at the counter. A Terminal that is offline or busy fails the refund before anything is sent; retry with a new idempotency key. If the Terminal’s answer is unclear, the refund returns 504 GATEWAY_UNCERTAIN and stays uncertain with its amount held. Ionic never sends it again or through another channel, and a sale on that Terminal can start right away.

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 built-in simulated Terminal is provided as 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	Ionic automatically for every test account	`POST /terminal_provisioning_requests`
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

List a test account’s simulated Terminals with GET /terminals, choose one by test_profile, and retain its Account-owned tmr_…. The default profile works through the normal PaymentIntent processing call without a helper. Use an exact Terminal payment override only when a focused test needs a different outcome for one PaymentIntent. 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.

​Related objects

​Refund receipts

​Refunds on the Terminal

​Three independent states

​Status

​Connection status

​Capabilities

​Simulated and physical Terminals

​Identifiers

Related objects