> ## Documentation Index
> Fetch the complete documentation index at: https://docs.telzino.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Transactions

> Read the payment ledger across all your merchants, with masked customer references

Read-only payment ledger, strictly scoped to organizations owned by your account. Customer references are masked. Supports filtering by status, organization, and a free-text search over Stripe ids / customer.

<Note>
  This endpoint reflects charges created by Telzino AI agents during calls — it does not create payments. An `organization_id` filter for an organization outside your account simply returns no rows.
</Note>

## Query Parameters

<ParamField query="status" type="string">
  Filter by transaction status. One of `created`, `paid`, `abandoned`, `failed`, `refunded`.
</ParamField>

<ParamField query="organization_id" type="string">
  Restrict results to a single merchant you own.

  **Example:** `123e4567-e89b-12d3-a456-426614174000`
</ParamField>

<ParamField query="search" type="string">
  Free-text search over Stripe ids and the (masked) customer reference.
</ParamField>

<ParamField query="limit" type="integer" default="50">
  Maximum rows to return. Capped at `100`.
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Number of rows to skip, for pagination.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.telzino.com/v1/payments/transactions?status=paid&limit=25" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({ status: 'paid', limit: '25' });

  const response = await fetch(
    `https://api.telzino.com/v1/payments/transactions?${params}`,
    { headers: { 'Authorization': 'Bearer YOUR_ACCESS_TOKEN' } }
  );

  const { transactions, count } = await response.json();
  ```

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

  response = requests.get(
      'https://api.telzino.com/v1/payments/transactions',
      params={'status': 'paid', 'limit': 25},
      headers={'Authorization': 'Bearer YOUR_ACCESS_TOKEN'}
  )

  transactions = response.json()['transactions']
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "transactions": [
      {
        "id": "e8c2b1a0-1111-2222-3333-444455556666",
        "organization_id": "123e4567-e89b-12d3-a456-426614174000",
        "merchant_name": "Acme Solar",
        "created_at": "2026-07-18T14:03:21.000Z",
        "amount": 4999,
        "currency": "usd",
        "status": "paid",
        "customer": "+1••••••1234",
        "stripe_checkout_session_id": "cs_test_a1B2c3...",
        "stripe_payment_intent_id": "pi_3AbC..."
      }
    ],
    "limit": 25,
    "offset": 0,
    "count": 1
  }
  ```

  ```json 400 theme={null}
  {
    "error": "Invalid status",
    "error_description": "status must be one of created, paid, abandoned, failed, refunded"
  }
  ```

  ```json 401 theme={null}
  {
    "error": "unauthorized",
    "error_description": "User payload not found"
  }
  ```
</ResponseExample>

## Response Fields

### Transactions Array

| Field                        | Type           | Description                                             |
| ---------------------------- | -------------- | ------------------------------------------------------- |
| `id`                         | string         | Transaction UUID                                        |
| `organization_id`            | string         | Merchant UUID the charge belongs to                     |
| `merchant_name`              | string         | Organization display name                               |
| `created_at`                 | string         | ISO 8601 timestamp                                      |
| `amount`                     | integer        | Amount in the currency's smallest unit (e.g. cents)     |
| `currency`                   | string         | ISO currency code (e.g. `usd`)                          |
| `status`                     | string         | `created`, `paid`, `abandoned`, `failed`, or `refunded` |
| `customer`                   | string         | Masked customer reference (e.g. partial phone number)   |
| `stripe_checkout_session_id` | string \| null | Stripe Checkout Session id, if any                      |
| `stripe_payment_intent_id`   | string \| null | Stripe PaymentIntent id, if any                         |

### Top Level

| Field    | Type    | Description                          |
| -------- | ------- | ------------------------------------ |
| `limit`  | integer | Effective page size used             |
| `offset` | integer | Offset applied                       |
| `count`  | integer | Number of rows returned in this page |