> ## 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.

# Get Transactions | Payments API

> Retrieve transactions via the Atoa Payments API, request parameters, response schema and code samples in cURL, Python, JavaScript, PHP, Go and Java.

Returns a paginated list of transactions for the authenticated merchant. Use filters to narrow down results by date, status, payment method, customer, or store.

### Authorization

Bearer `<accessSecret>`

**Query Parameters**

<ParamField query="page" type="number" default="0">
  Page number (0-indexed).
</ParamField>

<ParamField query="size" type="number" default="20">
  Number of items per page.
</ParamField>

**Request Body Schema**

All fields are optional. Omit the field to skip filtering.

<Note>
  Array filters must have at least 1 item when provided. Passing an empty array `[]` will return a validation error.
</Note>

<ParamField body="search" type="string">
  Free-text search by consumer name, order ID, payment request ID, or amount.
</ParamField>

<ParamField body="fromDate" type="string">
  Start date in `YYYY-MM-DD` format. Example: `2025-01-01`.
</ParamField>

<ParamField body="toDate" type="string">
  End date in `YYYY-MM-DD` format. Example: `2025-12-31`.
</ParamField>

<ParamField body="status" type="string[]">
  Filter by payment status.

  <Accordion title="Possible values">
    * `COMPLETED` — Payment successfully captured
    * `FAILED` — Payment failed
    * `PENDING` — Payment is being processed
    * `REFUNDED` — Payment fully refunded
    * `PARTIALLY_REFUNDED` — Payment partially refunded
    * `AUTHORIZED` — Payment authorized, not yet captured (MANUAL\_CAPTURE)
    * `CANCELLED` — Payment was cancelled
  </Accordion>
</ParamField>

<ParamField body="atoaCustomerIds" type="string[]">
  Filter by Atoa customer UUIDs (from [Create Customer](/api-reference/Customers/create-customer)). Each must be a valid UUID.
</ParamField>

<ParamField body="paymentMethod" type="string[]">
  Filter by payment method.

  <Accordion title="Possible values">
    * `PAY_BY_BANK` — Open banking payments
    * `CARD` — Card payments
  </Accordion>
</ParamField>

<ParamField body="storeIds" type="string[]">
  Filter by store UUIDs. Each must be a valid UUID.
</ParamField>

**Response**

<ResponseField name="data" type="array">
  <Expandable>
    <ResponseField name="paymentIdempotencyId" type="string">
      Unique transaction identifier (e.g., `ATOA1692417435050`).
    </ResponseField>

    <ResponseField name="paymentRequestId" type="string">
      Payment request UUID.
    </ResponseField>

    <ResponseField name="customerId" type="string">
      Customer UUID.
    </ResponseField>

    <ResponseField name="orderId" type="string">
      Merchant order reference.
    </ResponseField>

    <ResponseField name="consumerName" type="string">
      Customer name.
    </ResponseField>

    <ResponseField name="paidAmount" type="number">
      Amount paid.
    </ResponseField>

    <ResponseField name="currency" type="string">
      Currency code (e.g., `GBP`).
    </ResponseField>

    <ResponseField name="status" type="string">
      Transaction status (COMPLETED, FAILED, PENDING, REFUNDED, PARTIALLY\_REFUNDED, AUTHORIZED, CANCELLED).
    </ResponseField>

    <ResponseField name="transactionType" type="string">
      `CARD` for card payments, `OPEN_BANKING` for Pay by Bank.
    </ResponseField>

    <ResponseField name="notes" type="string">
      Payment notes.
    </ResponseField>

    <ResponseField name="metadata" type="object">
      Only present when metadata was supplied on the payment. See [Process Payment](/api-reference/Payment/process-payment) for the field limits.
    </ResponseField>

    <ResponseField name="storeDetails" type="object">
      <Expandable>
        <ResponseField name="id" type="string">
          Store UUID.
        </ResponseField>

        <ResponseField name="address" type="string">
          Store address.
        </ResponseField>

        <ResponseField name="locationName" type="string">
          Store name.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="errorDescription" type="string">
      Error description for failed payments.
    </ResponseField>

    <ResponseField name="cardPaymentDetails" type="object">
      Card-specific details. Only present for card transactions (`transactionType: "CARD"`). The `metadata.isMitPayment` field indicates whether this was a merchant-initiated [card-on-file](/api-reference/CardOnFile/introduction) payment.

      <Expandable>
        <ResponseField name="cardType" type="string">
          Card brand (e.g., `VISA`, `MASTERCARD`).
        </ResponseField>

        <ResponseField name="transactionSubType" type="string">
          `CARD`, `GOOGLE_PAY`, or `APPLE_PAY`.
        </ResponseField>

        <ResponseField name="captureType" type="string">
          `AUTO_CAPTURE`, `MANUAL_CAPTURE`, or `CAPTURE_BEFORE_EXPIRY`.
        </ResponseField>

        <ResponseField name="metadata" type="object">
          Card payment metadata. `isMitPayment: true` indicates a merchant-initiated [card-on-file](/api-reference/CardOnFile/introduction) payment.
        </ResponseField>

        <ResponseField name="paymentMethodId" type="string">
          The card/payment method ID used.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 creation timestamp.
    </ResponseField>

    <ResponseField name="updatedAt" type="string">
      ISO 8601 last update timestamp.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="totalCount" type="number">
  Total number of transactions matching the filters.
</ResponseField>

<ResponseField name="page" type="number">
  Current page number.
</ResponseField>

<ResponseField name="size" type="number">
  Items per page.
</ResponseField>

<RequestExample>
  ```bash curl theme={null}
  curl --request POST \
    --url 'https://api.atoa.me/api/payments/transactions?page=0&size=20' \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
    "fromDate": "2025-01-01",
    "toDate": "2025-12-31",
    "status": ["COMPLETED", "AUTHORIZED"],
    "paymentMethod": ["CARD"]
  }'
  ```

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

  url = "https://api.atoa.me/api/payments/transactions"
  params = {"page": 0, "size": 20}
  payload = {
      "fromDate": "2025-01-01",
      "toDate": "2025-12-31",
      "status": ["COMPLETED", "AUTHORIZED"],
      "paymentMethod": ["CARD"]
  }
  headers = {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
  }

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

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.atoa.me/api/payments/transactions?page=0&size=20",
    {
      method: "POST",
      headers: {
        Authorization: "Bearer <token>",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        fromDate: "2025-01-01",
        toDate: "2025-12-31",
        status: ["COMPLETED", "AUTHORIZED"],
        paymentMethod: ["CARD"],
      }),
    }
  );

  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/payments/transactions?page=0&size=20",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => json_encode([
      "fromDate" => "2025-01-01",
      "toDate" => "2025-12-31",
      "status" => ["COMPLETED", "AUTHORIZED"],
      "paymentMethod" => ["CARD"]
    ]),
    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 (
    "fmt"
    "strings"
    "net/http"
    "io/ioutil"
  )

  func main() {
    url := "https://api.atoa.me/api/payments/transactions?page=0&size=20"
    payload := strings.NewReader(`{
      "fromDate": "2025-01-01",
      "toDate": "2025-12-31",
      "status": ["COMPLETED", "AUTHORIZED"],
      "paymentMethod": ["CARD"]
    }`)

    req, _ := http.NewRequest("POST", url, 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/payments/transactions?page=0&size=20")
    .header("Authorization", "Bearer <token>")
    .header("Content-Type", "application/json")
    .body("{\"fromDate\":\"2025-01-01\",\"toDate\":\"2025-12-31\",\"status\":[\"COMPLETED\",\"AUTHORIZED\"],\"paymentMethod\":[\"CARD\"]}")
    .asString();
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": [
      {
        "paymentIdempotencyId": "ATOA1692417435050",
        "paymentRequestId": "9baa68d8-362a-4127-994d-2ea622ef35ee",
        "customerId": "550e8400-e29b-41d4-a716-446655440000",
        "consumerId": "consumer_123",
        "merchantName": "My Shop",
        "merchantId": "eed6202f-4dfd-42fc-9bc6-48323556b59d",
        "orderId": "ORDER-001",
        "consumerName": "John Doe",
        "paidAmount": 10.50,
        "currency": "GBP",
        "status": "COMPLETED",
        "transactionType": "CARD",
        "notes": "Payment for order #001",
        "metadata": {
          "bookingId": "BK-42427",
          "orderReference": "ORD-1"
        },
        "storeDetails": {
          "id": "d77e02d5-4e93-46cf-a8be-50da650df562",
          "address": "London",
          "locationName": "London Store"
        },
        "cardPaymentDetails": {
          "cardType": "VISA",
          "transactionSubType": "CARD",
          "captureType": "AUTO_CAPTURE",
          "metadata": {
            "isMitPayment": true
          },
          "paymentMethodId": "card_abc123def456"
        },
        "createdAt": "2025-06-15T10:30:00.000Z",
        "updatedAt": "2025-06-15T10:31:00.000Z"
      }
    ],
    "totalCount": 100,
    "page": 0,
    "size": 20
  }
  ```

  ```json 400 theme={null}
  {
    "name": "BAD_REQUEST",
    "message": "From date must be in YYYY-MM-DD format.",
    "status": 400,
    "errors": []
  }
  ```
</ResponseExample>