> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.paywithatoa.co.uk/llms.txt
> Use this file to discover all available pages before exploring further.

# List Terminals (PAX) for Remote Payments

> List the PAX card terminals registered to your Atoa account via the API, ready to accept remote card and Pay by Bank payments.

Returns the POS terminals registered against the merchant, resolved from the SDK API key you authenticate with.

<Note>
  Live online status (`online` and `lastActive`) is resolved via a real-time
  presence lookup against the terminals' push-notification devices. This runs
  **by default** — `availability` defaults to `true`. Pass `availability: false`
  in the body to skip the lookup (the request is then faster); `online` is
  returned as `false` and `lastActive` as `null`.
</Note>

### Authorization

Bearer `<token>`

**Body**

<ParamField body="storeIds" type="string[]" optional>
  Filter terminals by one or more stores. Each value must be a valid store UUID.
  **If omitted, terminals across all of the merchant's stores are returned.**
</ParamField>

<ParamField body="availability" type="boolean" default="true">
  When `true` (the default), performs a live presence lookup and populates the
  `online` and `lastActive` fields for each terminal. Pass `false` to skip the
  lookup; those fields are then not resolved (`online` is `false`, `lastActive`
  is `null`).
</ParamField>

**Response**

Returns an array of POS terminal objects.

<ResponseField name="id" type="string" required>
  Primary key of the POS terminal. Use this value as the `id` when
  initiating a remote payment.
</ResponseField>

<ResponseField name="name" type="string">
  Human-readable name of the POS terminal. Can be `null` when no name is set.
</ResponseField>

<ResponseField name="serialNumber" type="string" required>
  Hardware serial number of the POS terminal device.
</ResponseField>

<ResponseField name="storeId" type="string">
  ID of the store the terminal belongs to.
</ResponseField>

<ResponseField name="online" type="boolean" required>
  Whether the device is currently online according to its push-notification
  presence. Only meaningful when the request was made with `availability: true`
  (the default); otherwise always `false`.
</ResponseField>

<ResponseField name="lastActive" type="number">
  Unix timestamp (in seconds) of the device's last presence activity. `null`
  when unknown or when `availability: false` was sent.
</ResponseField>

<ResponseField name="tokenMissing" type="boolean" required>
  `true` when no push-notification device token is registered against the
  terminal. Such a terminal cannot receive remote payments and will always
  report `online: false`.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://api.atoa.me/api/terminal/list' \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "storeIds": [
        "43c7b991-0803-4177-9589-d165d9a779f6",
        "9f8e7d6c-5b4a-3210-fedc-ba9876543210"
      ],
      "availability": true
    }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.atoa.me/api/terminal/list"
  payload = {
      "storeIds": [
          "43c7b991-0803-4177-9589-d165d9a779f6",
          "9f8e7d6c-5b4a-3210-fedc-ba9876543210",
      ],
      "availability": True,
  }
  headers = {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json",
  }

  response = requests.post(url, json=payload, headers=headers)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.atoa.me/api/terminal/list", {
    method: "POST",
    headers: {
      Authorization: "Bearer <token>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      storeIds: [
        "43c7b991-0803-4177-9589-d165d9a779f6",
        "9f8e7d6c-5b4a-3210-fedc-ba9876543210",
      ],
      availability: true,
    }),
  });

  const data = await response.json();
  console.log(data);
  ```

  ```php PHP theme={null}
  <?php

  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.atoa.me/api/terminal/list",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => json_encode([
      "storeIds" => [
        "43c7b991-0803-4177-9589-d165d9a779f6",
        "9f8e7d6c-5b4a-3210-fedc-ba9876543210",
      ],
      "availability" => true,
    ]),
    CURLOPT_HTTPHEADER => [
      "Authorization: Bearer <token>",
      "Content-Type: application/json"
    ],
  ]);

  $response = curl_exec($curl);
  curl_close($curl);
  echo $response;
  ```

  ```go Go theme={null}
  package main

  import (
    "bytes"
    "fmt"
    "net/http"
    "io/ioutil"
  )

  func main() {
    url := "https://api.atoa.me/api/terminal/list"
    payload := []byte(`{"storeIds":["43c7b991-0803-4177-9589-d165d9a779f6","9f8e7d6c-5b4a-3210-fedc-ba9876543210"],"availability":true}`)

    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(payload))
    req.Header.Add("Authorization", "Bearer <token>")
    req.Header.Add("Content-Type", "application/json")

    res, _ := http.DefaultClient.Do(req)
    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)
    fmt.Println(string(body))
  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://api.atoa.me/api/terminal/list")
    .header("Authorization", "Bearer <token>")
    .header("Content-Type", "application/json")
    .body("{\"storeIds\":[\"43c7b991-0803-4177-9589-d165d9a779f6\",\"9f8e7d6c-5b4a-3210-fedc-ba9876543210\"],\"availability\":true}")
    .asString();
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  [
    {
      "id": "1",
      "name": "Front Till",
      "serialNumber": "100200300",
      "storeId": "43c7b991-0803-4177-9589-d165d9a779f6",
      "online": true,
      "lastActive": 1720512000,
      "tokenMissing": false
    }
  ]
  ```

  ```json 401 theme={null}
  {
    "name": "UNAUTHORIZED",
    "message": "Unauthorized",
    "status": 401,
    "errors": "[]"
  }
  ```

  ```json 500 theme={null}
  {
    "name": "INTERNAL_SERVER_ERROR",
    "message": "Internal Server Error",
    "status": 500,
    "errors": "[]"
  }
  ```
</ResponseExample>