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

# List Payments — GET /payments | ByDoctor API Reference

> GET /payments — retrieve a paginated list of payments. Filter by appointment, status, method, or date range for financial reporting.

The **List Payments** endpoint returns a paginated collection of payment records associated with your clinic. You can narrow results using filters for appointment, status, payment method, or a creation date range — making it straightforward to pull the data you need for financial reconciliation and reporting.

## Endpoint

```
GET https://api.bydoctor.com.br/v1/payments
```

## Authentication

Include your API key as a Bearer token in the `Authorization` header of every request.

```
Authorization: Bearer YOUR_API_KEY
```

## Query Parameters

<ParamField query="limit" type="integer" default="20">
  Number of payment records to return per page. Maximum value is `100`.
</ParamField>

<ParamField query="cursor" type="string">
  Pagination cursor returned in the previous response's `meta.next_cursor`. Omit this parameter to start from the beginning.
</ParamField>

<ParamField query="appointment_id" type="string">
  Filter payments by a specific appointment UUID. Useful for retrieving all payment entries — including partial payments — linked to a single visit.
</ParamField>

<ParamField query="status" type="string">
  Filter by payment status. Accepted values: `pending`, `paid`, `cancelled`.
</ParamField>

<ParamField query="method" type="string">
  Filter by payment method. Accepted values: `cash`, `credit_card`, `debit_card`, `pix`, `health_plan`.
</ParamField>

<ParamField query="created_after" type="string">
  Return only payments created at or after this timestamp. Must be a valid ISO 8601 UTC datetime (e.g. `2024-01-01T00:00:00Z`).
</ParamField>

<ParamField query="created_before" type="string">
  Return only payments created at or before this timestamp. Must be a valid ISO 8601 UTC datetime (e.g. `2024-01-31T23:59:59Z`).
</ParamField>

## Response Fields

The response is wrapped in a standard paginated envelope.

<ResponseField name="data" type="array">
  Array of payment objects matching your query filters.

  <Expandable title="Payment object fields">
    <ResponseField name="id" type="string">
      Unique identifier for the payment (UUID).
    </ResponseField>

    <ResponseField name="clinic_id" type="string">
      Identifier of the clinic that owns this payment record.
    </ResponseField>

    <ResponseField name="appointment_id" type="string">
      UUID of the appointment this payment is linked to.
    </ResponseField>

    <ResponseField name="amount" type="integer">
      Payment amount in centavos (BRL). For example, `15000` equals R\$ 150,00.
    </ResponseField>

    <ResponseField name="method" type="string">
      Payment method used. One of: `cash`, `credit_card`, `debit_card`, `pix`, `health_plan`.
    </ResponseField>

    <ResponseField name="bank_account_id" type="string">
      UUID of the destination bank account, if one was specified at creation. May be `null`.
    </ResponseField>

    <ResponseField name="status" type="string">
      Current payment status. One of: `pending`, `paid`, `cancelled`.
    </ResponseField>

    <ResponseField name="notes" type="string">
      Optional free-text notes attached to the payment. May be `null`.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 UTC timestamp of when the payment record was created.
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 UTC timestamp of the most recent update to this record.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  Pagination and summary metadata for the current result set.

  <Expandable title="Meta fields">
    <ResponseField name="meta.total" type="integer">
      Total number of payments matching the applied filters across all pages.
    </ResponseField>

    <ResponseField name="meta.has_more" type="boolean">
      `true` if there are additional pages of results beyond the current page.
    </ResponseField>

    <ResponseField name="meta.next_cursor" type="string">
      Cursor value to pass as the `cursor` query parameter to retrieve the next page. `null` when `has_more` is `false`.
    </ResponseField>
  </Expandable>
</ResponseField>

<Note>
  The `meta.total` field reflects the count of payments that match your active filters — not the total number of payments in your clinic. When combined with `created_after` and `created_before`, this makes it easy to sum revenue for a specific reporting period without fetching every page.
</Note>

## Error Responses

| Status             | Code             | Description                                                         |
| ------------------ | ---------------- | ------------------------------------------------------------------- |
| `400 Bad Request`  | `invalid_status` | The `status` value is not one of `pending`, `paid`, or `cancelled`. |
| `400 Bad Request`  | `invalid_method` | The `method` value is not one of the accepted payment methods.      |
| `401 Unauthorized` | `unauthorized`   | Your API key is missing or invalid.                                 |

## Example Request

```bash theme={null}
curl --request GET \
  --url "https://api.bydoctor.com.br/v1/payments?status=paid&created_after=2024-06-01T00:00:00Z&created_before=2024-06-30T23:59:59Z&limit=2" \
  --header "Authorization: Bearer YOUR_API_KEY"
```

## Example Response

```json theme={null}
{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "clinic_id": "clinic_01HXYZ",
      "appointment_id": "appt_01HABC",
      "amount": 25000,
      "method": "pix",
      "bank_account_id": "ba_01HBANK1",
      "status": "paid",
      "notes": null,
      "created_at": "2024-06-03T14:22:10Z",
      "updated_at": "2024-06-03T14:23:05Z"
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "clinic_id": "clinic_01HXYZ",
      "appointment_id": "appt_01HDEF",
      "amount": 18000,
      "method": "credit_card",
      "bank_account_id": null,
      "status": "paid",
      "notes": "Patient paid in full at reception.",
      "created_at": "2024-06-05T09:47:33Z",
      "updated_at": "2024-06-05T09:47:33Z"
    }
  ],
  "meta": {
    "total": 47,
    "has_more": true,
    "next_cursor": "cursor_eyJpZCI6ImIyYzNkNGU1In0"
  }
}
```