Terminal Lifecycle (Concepts)

Overview

This page explains the life cycle of a terminal—from first creation to final retirement—and shows which API calls you typically use at each phase. The model now follows a top-level POST /Terminals pattern: you include the locationId in the request body instead of calling a nested location URL.

Phases

Phase	Goal	Typical calls
Provision	Register a new physical device or virtual endpoint.	POST /Terminals
Configure	Add a name, description, tender types, webhooks, or custom metadata.	PATCH / PUT /Terminals/{id}PUT /Terminals/{id}/webhook
Operate	Use the terminal to create payment sessions; monitor status through webhooks or reporting.	Payment APIs Reporting APIs
Retire	Disable or delete the terminal when it is no longer needed.	PATCH /Terminals/{id} (isEnabled=false) DELETE /Terminals/{id}

Provision

Send POST /Terminals with a JSON body that contains at least the locationId. The service returns a unique terminalId you will use in every payment request.

{
  "locationId": "loc_bfdc6a7f",
  "name": "Front Counter POS"
}

Configure

Call PATCH or PUT /Terminals/{id} to set any optional fields. Use PATCH when changing a single property, use PUT when you want to replace all editable fields in one call.

Operate

Pass terminalId whenever you create payment pages or other transaction requests. Webhooks and reporting endpoints include the same terminalId so you can trace each transaction back to the device.

Retire

Disable the terminal first, then delete it when you are certain no active sessions remain. Disabling keeps historical data intact while preventing new payments.

Hierarchy recap

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

Terminals belong to a location, which belongs to a merchant. Including the correct locationId when you create a terminal keeps reporting and permission models clean.

Call flow example

1. Create a location (if it does not already exist).

2. POST /Terminals with the locationId returned in step 1.

3. PATCH /Terminals/{id} to add a friendly name and enable needed tender types.

4. Optional – PUT /Terminals/{id}/webhook to receive device-level events.

5. Use the terminal in payment flows.

6. When the device is decommissioned, set isEnabled=false or DELETE /Terminals/{id}.

Best practices

• Create under the right location – Pass the correct locationId during creation so dashboards aggregate by store.

• PATCH vs. PUT – Use PATCH for small tweaks; reserve PUT for bulk updates.

• Disable before delete – Disable production devices before deleting to prevent accidental transactions.

• Webhooks – Prefer a merchant- or location-level webhook for large estates; use terminal-level webhooks only when necessary.