Register POS Terminal

Adds a new Point-of-Sale (POS) terminal record to a merchant account.

Authentication required (User JWT).

POST /api/merchants/:merchantId/pos-terminals

Path Parameters

Parameter	Type	Description
merchantId	String	The ID of the parent merchant.

Request Body

{
  "serialNumber": "SN123456789",
  "terminalId": "TID98765", // Optional: Manufacturer/Provider ID
  "model": "PAX A920", // Optional
  "linkedVirtualAccountNumber": "0123456789" // Optional: Link to existing VA on register
}

Field	Type	Required	Description
serialNumber	String	Yes	Unique serial number identifying the physical device.
terminalId	String	No	ID assigned by the terminal manufacturer or provider.
model	String	No	Model name/number of the terminal.
linkedVirtualAccountNumber	String	No	Account number of an existing Virtual Account belonging to this merchant to link for settlement.

Response 201 Created

Returns the details of the newly registered POS terminal.

{
  "message": "POS Terminal registered successfully",
  "terminal": {
    "serialNumber": "SN123456789",
    "merchantId": "uuid-merchant-456",
    "terminalId": "TID98765",
    "model": "PAX A920",
    "status": "INACTIVE", // Starts as inactive
    "linkedVirtualAccountNumber": "0123456789",
    "createdAt": "2023-10-27T12:00:00.000Z",
    "updatedAt": "2023-10-27T12:00:00.000Z"
    // Excludes merchant object, includes linkedVirtualAccount object if relation loaded
  }
}

Errors

• 400 Bad Request: Validation failed.
• 401 Unauthorized: Invalid or missing JWT.
• 404 Not Found: Merchant or linked Virtual Account not found.
• 409 Conflict: Terminal with this serial number already exists.
• 500 Internal Server Error