> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paywithatoa.com/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**

**page** `number` (default: 0)

Page number (0-indexed).

**size** `number` (default: 20)

Number of items per page.

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

**search** `string`

Free-text search by consumer name, order ID, payment request ID, or amount.

**fromDate** `string`

Start date in `YYYY-MM-DD` format. Example: `2025-01-01`.

**toDate** `string`

End date in `YYYY-MM-DD` format. Example: `2025-12-31`.

**status** `string[]`

Filter by payment status.

> **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

**atoaCustomerIds** `string[]`

Filter by Atoa customer UUIDs (from [Create Customer](https://docs.paywithatoa.com/api-reference/customers/create-customer.md)). Each must be a valid UUID.

**paymentMethod** `string[]`

Filter by payment method.

> **Possible values**
>
> * `PAY_BY_BANK` — Open banking payments
> * `CARD` — Card payments

**storeIds** `string[]`

Filter by store UUIDs. Each must be a valid UUID.

**Response**

**data** `array`

**paymentIdempotencyId** `string`

Unique transaction identifier (e.g., `ATOA1692417435050`).

**paymentRequestId** `string`

Payment request UUID.

**customerId** `string`

Customer UUID.

**orderId** `string`

Merchant order reference.

**consumerName** `string`

Customer name.

**paidAmount** `number`

Amount paid.

**currency** `string`

Currency code (e.g., `GBP`).

**status** `string`

Transaction status (COMPLETED, FAILED, PENDING, REFUNDED, PARTIALLY\_REFUNDED, AUTHORIZED, CANCELLED).

**transactionType** `string`

`CARD` for card payments, `OPEN_BANKING` for Pay by Bank.

**notes** `string`

Payment notes.

**metadata** `object`

Only present when metadata was supplied on the payment. See [Process Payment](https://docs.paywithatoa.com/api-reference/payment/process-payment.md) for the field limits.

**storeDetails** `object`

**id** `string`

Store UUID.

**address** `string`

Store address.

**locationName** `string`

Store name.

**errorDescription** `string`

Error description for failed payments.

**cardPaymentDetails** `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](https://docs.paywithatoa.com/api-reference/card-on-file/introduction.md) payment.

**cardType** `string`

Card brand (e.g., `VISA`, `MASTERCARD`).

**transactionSubType** `string`

`CARD`, `GOOGLE_PAY`, or `APPLE_PAY`.

**captureType** `string`

`AUTO_CAPTURE`, `MANUAL_CAPTURE`, or `CAPTURE_BEFORE_EXPIRY`.

**metadata** `object`

Card payment metadata. `isMitPayment: true` indicates a merchant-initiated [card-on-file](https://docs.paywithatoa.com/api-reference/card-on-file/introduction.md) payment.

**paymentMethodId** `string`

The card/payment method ID used.

**createdAt** `string`

ISO 8601 creation timestamp.

**updatedAt** `string`

ISO 8601 last update timestamp.

**totalCount** `number`

Total number of transactions matching the filters.

**page** `number`

Current page number.

**size** `number`

Items per page.

```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();
```

```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": []
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.