Submit Stage-Only Terminal

Creates a stage-only terminal record for a merchant in Netevia HQ without fully boarding it to TSYS. The staged terminal is pre-configured using the merchant's existing profile data and terminal alias, allowing a VAR sheet to be generated or the terminal to be activated later. On success, the response returns the assigned terminal ID and its initial status (typically New).

Endpoint

POST /api/v1/merchant/stageOnlyTerminal

Authentication

Basic HTTP Authentication required. Encode username:password in Base64 and pass in the Authorization header:

Authorization: Basic {base64(username:password)}

When to use

Use this endpoint when you need to pre-stage a terminal for a merchant before full TSYS boarding is complete — for example, when generating a VAR sheet ahead of equipment delivery, or when configuring a terminal that will go live at a future date. This is the preferred approach when you want to prepare terminal configuration without immediately submitting it to the processor. To both stage and board in a single call, use POST /api/v1/merchant/terminal instead.

Query Parameters

Parameter	Type	Required	Description
merchantProfileId	integer (int32)	Yes	Merchant profile ID for which the stage-only terminal is being created

Response

200 OK

Field	Type	Description
terminalId	integer	Unique ID assigned to the newly staged terminal
status	string (enum)	Current status of the terminal. One of: `New`, `Submitted`, `Changed`, `Closed`, `CloseTemporary`, `NotSubmitted`
requestId	integer	Unique request ID for tracking and debugging
success	boolean	True if the terminal was staged successfully
error	string	Error message on failure; null on success
validationErrors	array	Field-level validation errors, if any

{
  "terminalId": 4821,
  "status": "New",
  "requestId": 78334,
  "success": true,
  "error": null,
  "validationErrors": []
}

Error Codes

Code	When it happens
400	`merchantProfileId` is missing or not a valid integer
401	Invalid or missing Basic Auth credentials
403	User does not have permission for this operation
404	No merchant profile found for the given `merchantProfileId`
500	Internal server error during terminal staging

Common Mistakes

Using this endpoint when you intend to immediately board the terminal to TSYS — for full boarding, use POST /api/v1/merchant/terminal with a SubmitTerminalRequest body
Passing a string for merchantProfileId — it must be a valid int32 integer
Not saving the returned terminalId — this ID is required for subsequent operations such as generating a VAR sheet or transitioning the terminal to Submitted status
Expecting the terminal to be immediately active — stage-only terminals begin with status New and require an additional boarding step before processing payments

Related Endpoints

POST /api/v1/merchant/terminal — submit a terminal for full staging and TSYS boarding in a single operation
GET /api/v1/merchant/equipment — view all equipment (including staged terminals) assigned to a merchant
GET /api/v1/equipment/pos — retrieve the POS equipment catalog to identify the correct terminal type
POST /api/v1/equipment/equipmentpos — add POS equipment to the merchant application before terminal boarding

Example

curl -X POST "https://hq.staging.netevia.dev/api/v1/merchant/stageOnlyTerminal?merchantProfileId=78234" \
  -H "Authorization: Basic $(echo -n 'username:password' | base64)" \
  -H "Content-Type: application/json"

200OK