The PIN Pad Mediator exposes the following API methods for client applications.

Access token

Get the authorization token required for all subsequent requests. The token should be refreshed periodically.

POST /api/pinpad/token

Request

{
  "clientId": "string",
  "secret": "string"
}

• clientId and secret – client credentials (provided by Netevia)

Response

{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Errors

• 400 — missing clientId or secret
• 401 — invalid credentials

Available PIN Pads

Get the list of PIN Pads currently connected to the Mediator and available for communication.

GET /api/pinpad

Response

[
  {
    "serialNumber": "PAX123456789",
    "connectedAt": "2026-02-27T12:34:56.789Z",
    "lastSeen": "2026-02-27T12:35:10.123Z"
  }
]

• serialNumber – the serial number of the available PIN Pad

Errors

• 401 — missing or invalid access token

PIN Pad request

Send a request to a certain PIN Pad.

POST /api/pinpad/request

Request

{
  "pinPadSerialNumber": "PAX123456789",
  "body": { /* message for PIN Pad */ }
}

• pinPadSerialNumber – the serial number of the target PIN Pad
• body – a JSON object with a message to the PIN Pad.
  See the Message format and next sections for further details about the PIN Pad message protocol.

Response

{
  "requestId": "67c07f2af2a2c1f6a1b2c3d4"
}

Errors

• 400 — missing pinPadSerialNumber or request body
• 401 — missing or invalid access token
• 403 — PIN Pad belongs to another accountId
• 404 — PIN Pad not connected / connection lost
• 409 — request already in progress (duplicate request ID)
• 500 — failed to send a request

PIN Pad response check

Check if the Mediator has received a response from the PIN Pad.

This API method should be called periodically (polled) until a PIN Pad response is available – start with a short interval and increase it (backoff) to avoid overloading the Mediator.

GET /api/pinpad/request/{requestId}?pinPadSerialNumber={serialNumber}

Request parameters

• requestId – the ID of the original request received earlier
• pinPadSerialNumber – the serial number of the PIN Pad

Response

{
  "requestId": "67c07f2af2a2c1f6a1b2c3d4",
  "pinPadSerialNumber": "PAX123456789",
  "status": "Completed",
  "responseBody": {
    ...
  }
}

• requestId – the original request ID
• pinPadSerialNumber – the serial number of the PIN Pad
• status – the status of the request
  • Pending – still waiting for a PIN Pad response
  • Completed – PIN Pad response received (does not indicate the success of the related transaction)
• response – the actual response message from the PIN Pad (see Message format)

Errors

• 400 — missing requestId or pinPadSerialNumber
• 401 — missing or invalid access token
• 404 — request not found or the PIN Pad is not connected