---
updatedAt: 2026-04-16T14:42:44.000Z
agentTools:
  projectIndex: https://pinpad.docs.netevia.com/llms.txt
---

# Mediator API

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

<br />

# Access token

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

**POST `/api/pinpad/token`**

### Request

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

* `clientId` and `secret` – client credentials (*provided by Netevia*)

### Response

```json
{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

### Errors

* `400` — missing `clientId` or `secret`
* `401` — invalid credentials

<Callout icon="🔐" theme="default">
  The received access token must be sent with all subsequent API requests as a request header:

  `Authorization: Bearer <accessToken>`
</Callout>

<br />

# Available PIN Pads

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

**GET `/api/pinpad`**

### Response

```json
[
  {
    "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

<br />

# PIN Pad request

Send a request to a certain PIN Pad.

**POST `/api/pinpad/request`**

### Request

```json
{
  "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](https://pinpad.docs.netevia.com/reference/message-format) and next sections for further details about the PIN Pad message protocol.

### Response

```json
{
  "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

<br />

# 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

```json
{
  "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](https://pinpad.docs.netevia.com/reference/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

<br />