Create Terminal

post

https://sandbox-api.softpoint.io/interface/v1/locations/YOUR_LOCATION_ID/terminals

Registers a new physical payment terminal at a location so it can accept card-present transactions.

Request Headers

Header	Required	Description
Authorization	Yes	Bearer YOUR_ACCESS_TOKEN
Content-Type	Yes	`application/json`

Request Parameters

Path Parameters:

Parameter	Type	Required	Description
location_id	integer	Yes	Location the terminal is registered to.

Request Body Fields:

Field	Type	Required	Description
global_manufacturer_terminal_id	integer	Yes	Device model identifier (manufacturer + model). See Device Model IDs below.
global_terminal_mode_id	integer	Yes	Operating mode of the terminal. See Terminal Mode IDs below.
global_tip_id	integer	No	Tip-prompt configuration. `1` = Before, `2` = Tip Adjust, `3` = No Tips.
serial_number	string	Yes	Device serial number. Must be unique. Max 100 characters.
name	string	Yes	Friendly name for the terminal, shown in the SoftPoint dashboard. Max 64 characters.
tid	string	No	Terminal ID assigned by the processor. Max 100 characters.
status	integer	No	`1` = active (default), `0` = inactive.
paired_terminal_id	integer	No	ID of the Tethered Terminal to link to this workstation.
screen_timeout	integer	No	Idle screen timeout, in seconds.
connected_reader	integer	No	Whether a card reader is attached. `1` = active, `0` = inactive (default).
allow_cash_payments	integer	No	Whether cash payments are allowed. `1` = active, `0` = inactive (default).
user_id	integer	No	ID of the current (acting) user.

Field Value Reference

Device Model IDs (`global_manufacturer_terminal_id`)

ID	Model
14	PAX A30
15	PAX A35
16	PAX A50
17	PAX A60
18	PAX A77
19	PAX A80
20	PAX A910
21	PAX A920
22	PAX A920 PRO
23	PAX A930
24	PAX Aries6
25	PAX Aries8
26	PAX E500
27	PAX E600
28	PAX E700
29	PAX E800
37	External Workstation
52	PAX IM30

Terminal Mode IDs (`global_terminal_mode_id`)

ID	Mode
1	Table Service
2	Quick Service
3	Payment Terminal
4	Kiosk
5	Kitchen Display
6	Dispenser Kiosk
7	External Workstation
8	Tethered Terminal
9	Security Terminal

Tip IDs (`global_tip_id`)

ID	Behavior
1	Before
2	Tip Adjust
3	No Tips

Request Example

{
  "global_manufacturer_terminal_id": 22,
  "global_terminal_mode_id": 3,
  "global_tip_id": 2,
  "serial_number": "RR4455566",
  "name": "Bar",
  "tid": "11",
  "status": 1
}

cURL Example

curl --request POST \
  --url https://sandbox-api.softpoint.io/interface/v1/locations/4004699/terminals \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "global_manufacturer_terminal_id": 22,
    "global_terminal_mode_id": 3,
    "global_tip_id": 2,
    "serial_number": "RR4455566",
    "name": "Bar",
    "tid": "11",
    "status": 1
  }'

Success Response

{
  "terminal": {
    "id": 666,
    "id_external": 1326,
    "status": 1,
    "serial_number": "RR4455566",
    "name": "Bar",
    "tid": "11"
  }
}

Response Fields

Field	Type	Description
terminal.id	integer	The new terminal's ID (used in payment calls).
terminal.id_external	integer	string
terminal.status	integer	Status. `1` = active, `0` = inactive.
terminal.serial_number	string	Registered serial number.
terminal.name	string	Friendly name.
terminal.tid	string	Processor-assigned terminal ID, if provided.

Error Responses

Duplicate Serial Number

{
  "error": {
    "code": 10106,
    "message": "This terminal serial number is already registered.",
    "details": null
  }
}

Status Codes

Code	Description
200	Terminal registered
400	Validation failed (for example, duplicate serial number)

Workflow Placement

Part of boarding, after the location exists and before card-present payments:

Create A Location
Create Terminal
Configure Processing (Card Present)
Card-present Sale / Auth

Notes

serial_number must be unique across the platform.
The returned terminal.id is what card-present webhooks reference as terminal_id.

Common Mistakes

Reusing a serial number (returns 10106).
Omitting the device model or mode identifiers.

Responses

200OK

400Bad Request