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

# Fetch Account Transactions

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

Once bank account access is authorized, use the following API to fetch transaction data.

<Note>
  This endpoint uses [**cursor-based pagination**](#cursor-based-pagination), returning one bank page per call. Follow `links.next` exactly as returned until it is no longer present to page through all transactions. Responses use the `{ data, meta, links }` envelope shown in the sample response below.
</Note>

### Authorization

Bearer `<token>`

**Request Body Schema**

<ParamField path="accountId" type="string" required>
  ID of the user's bank account. This can be obtained from the redirect URL
  after account linking or by using the [Fetch All Accounts API
  Reference](/api-reference/AccountInitiationServices/fetch-all-accounts)
  endpoint.

  Refer:- [Accounts](/accounts)
</ParamField>

<ParamField query="from" type="string">
  Inclusive lower bound on the booking date. Accepts either a plain
  date (e.g. `2025-08-17`) or a full ISO 8601 date-time (e.g.
  `2026-01-01T00:00:00Z`). **Only applies to the first call.** Once
  pagination has started, the date range is held inside the cursor,
  so `from` should not be sent again alongside a cursor.
</ParamField>

<ParamField query="before" type="string">
  Exclusive upper bound on the booking date. Accepts either a plain
  date (e.g. `2025-08-17`) or a full ISO 8601 date-time.
  **Only applies to the first call.** Should not be sent again
  alongside a cursor. `before` requires `from` to also be set.
</ParamField>

<ParamField query="cursor" type="string">
  Cursor token taken from a previous response's `links.next` or `links.prev`.
  Pass it back **unchanged** — do not read, decode, or modify it. A stale,
  tampered, or reused cursor returns `410 Gone`, signalling that the caller
  should restart pagination without a cursor.
</ParamField>

**Response**

<ResponseField name="data" type="array">
  Array of transactions. Each transaction has the following fields:

  <Expandable>
    <ResponseField name="id" type="string">
      A **unique identifier** for the transaction. Use this to deduplicate or
      track individual transactions.
    </ResponseField>

    <ResponseField name="date" type="string">
      The **most recent date associated with the transaction.** This may be the
      booking date or value date depending on the bank.
    </ResponseField>

    <ResponseField name="type" type="string">
      Indicates whether the transaction is a **CREDIT** (money received) or
      **DEBIT** (money sent).
    </ResponseField>

    <ResponseField name="amount" type="number">
      The **monetary value** of the transaction. This can be positive or
      negative based on the type.
    </ResponseField>

    <ResponseField name="currency" type="string">
      The **currency code** (e.g., GBP, EUR) in which the transaction was made.
    </ResponseField>

    <ResponseField name="description" type="string">
      Any **additional information or context** provided by the bank. This could
      include metadata, internal codes, or bank-provided notes.
    </ResponseField>

    <ResponseField name="merchantName" type="string" optional>
      The **name of the merchant** involved in the transaction, if provided by
      the bank.
    </ResponseField>

    <ResponseField name="transactionCategory" type="string">
      A **high-level category** indicating the nature of the transaction (e.g.,
      Payments, Transfers, ATM, etc.). Helps in transaction classification.
    </ResponseField>

    <ResponseField name="status" type="string">
      The **current state** of the transaction. Can be **BOOKED** (processed and
      settled) or **PENDING** (initiated but not yet fully processed).
    </ResponseField>

    <ResponseField name="payer" type="object" optional>
      The payer object provides information about the sender of the funds.

      <Expandable>
        <ResponseField name="name" type="string">
          The name of the payer.
        </ResponseField>

        <ResponseField name="accountDetails" type="object" optional>
          Account details of the payer. **Note: This field might not be
          available for some banks.**

          <Expandable>
            <ResponseField name="sortCode" type="string">
              Sort code of the payer's account.
            </ResponseField>

            <ResponseField name="accountNumber" type="string">
              Account number of the payer.
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="payee" type="object" optional>
      The payee object provides information about the recipient of the funds.

      <Expandable>
        <ResponseField name="name" type="string">
          The name of the payee.
        </ResponseField>

        <ResponseField name="accountDetails" type="object" optional>
          Account details of the payee. **Note: This field might not be
          available for some banks.**

          <Expandable>
            <ResponseField name="sortCode" type="string">
              Sort code of the payee's account.
            </ResponseField>

            <ResponseField name="accountNumber" type="string">
              Account number of the payee.
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="balance" type="object" optional>
      The account balance **immediately after** the transaction. **Note: This
      field might not be available for some banks.** Includes:

      <Expandable>
        <ResponseField name="amount" type="number">
          The available balance at that point in time.
        </ResponseField>

        <ResponseField name="currency" type="string">
          The currency in which the balance is held.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  Metadata for this page.

  <Expandable>
    <ResponseField name="count" type="number">
      Number of transactions in `data`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="links" type="object">
  Pagination links. Follow the URLs exactly as returned.

  <Expandable>
    <ResponseField name="self" type="string">
      URL of the current request.
    </ResponseField>

    <ResponseField name="next" type="string" optional>
      URL of the next page. Absent when there is no next page.
    </ResponseField>

    <ResponseField name="prev" type="string" optional>
      URL of the previous page. Only present if the bank provides it.
    </ResponseField>
  </Expandable>
</ResponseField>

### Cursor-based pagination

Atoa's `Get Account Transactions` endpoint uses cursor-based pagination. It accepts `from` and `before` as optional query parameters when sending the initial request, and accepts `cursor` as an optional query parameter in subsequent requests.

#### How it works

Atoa doesn't set a `limit` for the maximum number of transactions returned per page, but an individual bank can set a limit.

The `meta` object in the response includes `count` that represents the number of transactions in that page, but doesn't return a field for the total number of transactions.

The `data` object in the response contains an array of transactions.

The `links` object in the response returns cursor tokens that can be fed into the subsequent request:

* `prev` - a cursor or link to the previous page
* `self` - a cursor or link to the current page
* `next` - a cursor or link to the next page

#### Examples

<Tabs>
  <Tab title="First page">
    `GET /accounts/{accountId}/transactions` returns `self` and `next`.

    ```json theme={null}
    "links": {
      "self": "https://api.atoa.me/api/bank/accounts/{accountId}/transactions?cursor=<current-page-cursor>",
      "next": "https://api.atoa.me/api/bank/accounts/{accountId}/transactions?cursor=<next-page-cursor>"
    }
    ```
  </Tab>

  <Tab title="Middle page">
    `GET /accounts/{accountId}/transactions?cursor=<current-page-cursor>` returns `prev`, `self` and `next`.

    ```json theme={null}
    "links": {
      "prev": "https://api.atoa.me/api/bank/accounts/{accountId}/transactions?cursor=<prev-page-cursor>",
      "self": "https://api.atoa.me/api/bank/accounts/{accountId}/transactions?cursor=<current-page-cursor>",
      "next": "https://api.atoa.me/api/bank/accounts/{accountId}/transactions?cursor=<next-page-cursor>"
    }
    ```
  </Tab>

  <Tab title="Final page">
    `GET /accounts/{accountId}/transactions?cursor=<current-page-cursor>` returns `prev` and `self`.

    ```json theme={null}
    "links": {
      "prev": "https://api.atoa.me/api/bank/accounts/{accountId}/transactions?cursor=<prev-page-cursor>",
      "self": "https://api.atoa.me/api/bank/accounts/{accountId}/transactions?cursor=<current-page-cursor>"
    }
    ```
  </Tab>
</Tabs>

Pass the cursor back unchanged. An expired or tampered cursor returns `410 Gone`, at which point restart pagination without a cursor. Because the date range is held inside the cursor, later calls should not re-send `from` or `before` alongside it.

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": [
      {
        "id": "txn_001",
        "date": "2024-01-14T11:45:00Z",
        "type": "DEBIT",
        "amount": 89.99,
        "currency": "GBP",
        "description": "Amazon Marketplace",
        "reference": "INV-4321-A",
        "transactionCategory": "E-commerce",
        "status": "BOOKED",
        "payee": {
          "name": "Amazon UK Ltd",
          "accountDetails": {
            "sortCode": "123456",
            "accountNumber": "87654321"
          }
        },
        "balance": { "amount": 2.37, "currency": "GBP" }
      },
      {
        "id": "txn_002",
        "date": "2024-01-12T09:30:00Z",
        "type": "CREDIT",
        "amount": 1500.0,
        "currency": "GBP",
        "description": "Salary Payment",
        "reference": "SALARY-JAN",
        "transactionCategory": "Income",
        "status": "BOOKED",
        "payer": {
          "name": "ABC Company Ltd",
          "accountDetails": {
            "sortCode": "654321",
            "accountNumber": "12345678"
          }
        },
        "balance": { "amount": 1592.36, "currency": "GBP" }
      }
    ],
    "meta": { "count": 2 },
    "links": {
      "prev": "https://api.atoa.me/api/bank/accounts/{accountId}/transactions?cursor=<prev-page-cursor>",
      "self": "https://api.atoa.me/api/bank/accounts/{accountId}/transactions?cursor=<current-page-cursor>",
      "next": "https://api.atoa.me/api/bank/accounts/{accountId}/transactions?cursor=<next-page-cursor>"
    }
  }
  ```

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

  ```json 404 theme={null}
  {
    "name": "NOT FOUND",
    "message": "Consent not found",
    "status": 404,
    "errors": []
  }
  ```

  ```json 410 theme={null}
  {
    "name": "GONE",
    "message": "The pagination cursor is expired or invalid. Restart pagination without a cursor.",
    "status": 410,
    "errors": []
  }
  ```
</ResponseExample>