List Payments — GET /payments | ByDoctor API Reference

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

integer

default:"20"

Number of payment records to return per page. Maximum value is 100.

string

Pagination cursor returned in the previous response’s meta.next_cursor. Omit this parameter to start from the beginning.

string

Filter payments by a specific appointment UUID. Useful for retrieving all payment entries — including partial payments — linked to a single visit.

string

Filter by payment status. Accepted values: pending, paid, cancelled.

string

Filter by payment method. Accepted values: cash, credit_card, debit_card, pix, health_plan.

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

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

Response Fields

The response is wrapped in a standard paginated envelope.

array

Array of payment objects matching your query filters.

Show Payment object fields

string

Unique identifier for the payment (UUID).

string

Identifier of the clinic that owns this payment record.

string

UUID of the appointment this payment is linked to.

integer

Payment amount in centavos (BRL). For example, 15000 equals R$ 150,00.

string

Payment method used. One of: cash, credit_card, debit_card, pix, health_plan.

string

UUID of the destination bank account, if one was specified at creation. May be null.

string

Current payment status. One of: pending, paid, cancelled.

string

Optional free-text notes attached to the payment. May be null.

string

ISO 8601 UTC timestamp of when the payment record was created.

string

ISO 8601 UTC timestamp of the most recent update to this record.

object

Pagination and summary metadata for the current result set.

Show Meta fields

integer

Total number of payments matching the applied filters across all pages.

boolean

true if there are additional pages of results beyond the current page.

string

Cursor value to pass as the cursor query parameter to retrieve the next page. null when has_more is false.

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.

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

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

{
  "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"
  }
}

Appointments

Patients

Schedules & Availability

Payments

Webhooks

List Payments — GET /payments | ByDoctor API Reference

Endpoint

Authentication

Query Parameters

Response Fields

Error Responses

Example Request

Example Response

​Endpoint

​Authentication

​Query Parameters

​Response Fields

​Error Responses

​Example Request

​Example Response

Endpoint

Authentication

Query Parameters

Response Fields

Error Responses

Example Request

Example Response