get/v1/payments

List Payments

Returns Payments in the authenticated Organization. Filter optionally by patient_id and by a paid_at window. Each Payment includes invoice_id, patient_id, and nested refunds.

Required API scopes: payments.read

Parameters

patient_id
query
string
Filter by a Patient with an active connection to the Organization.
paid_at_from
query
string
Inclusive lower bound for paid_at in UTC ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ). Payments with a null paid_at are omitted when this filter is set.
paid_at_to
query
string
Inclusive upper bound for paid_at in UTC ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ). Payments with a null paid_at are omitted when this filter is set.
limit
query
integer
The maximum number of items to return. Defaults to 25; the maximum is 100.
starting_after
query
string
Return items after this resource ID. You cannot use this with cursor.
cursor
query
string
The next_cursor value from the previous page. You cannot use this with starting_after.

Responses

200

Paginated list of Payment objects.

dataarrayrequired
- itemsobject
  - amountintegerrequired
    The Payment amount in minor currency units.
  - created_atstring · date-timerequired
    An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
  - currencystring | nullrequired
    The ISO 4217 currency code.
  - idstring · uuidrequired
    The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - internal_notesstring | nullrequired
    Internal notes recorded with the Payment.
  - invoice_idstring | null · uuidrequired
    The Invoice this Payment is allocated to, when one is assigned.
  - linksobjectrequired
    URLs to related resources.
    - patientstring | null · urirequired
      The full URL of a related resource.
  - objectanyrequired
    Discriminator value emitted at object.
  - paid_atstring | null · date-timerequired
    An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
  - patient_idstring | null · uuidrequired
    The Patient associated with the Payment.
  - payment_method_typestring | nullrequired
    How the Payment was collected.
    Allowed values: bacs_debit | bank_transfer | card | card_external | cash | cheque | klarna | other | standing_order | null
  - payor_typestring | nullrequired
    The type of party who made the Payment.
    Allowed values: alternative_payor | insurance_company | location | patient | null
  - refundsarrayrequired
    Refunds issued against this Payment, if any. Ordered by created_at.
    - itemsobject
      - amountintegerrequired
        The refunded amount in minor currency units.
      - created_atstring · date-timerequired
        An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
      - currencystring | nullrequired
        The ISO 4217 currency code.
      - errorstring | nullrequired
        The failure message when the Refund did not complete.
      - idstring · uuidrequired
        The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
      - invoice_idstring | null · uuidrequired
        The Invoice associated with the refunded Payment, when one is assigned.
      - linksobjectrequired
        URLs to related resources.
        patientstring | null · urirequired
        The full URL of a related resource.
      - notesstring | nullrequired
        Internal notes recorded with the Refund.
      - objectanyrequired
        Discriminator value emitted at object.
      - patient_idstring | null · uuidrequired
        The Patient associated with the Refund.
      - payment_idstring | null · uuidrequired
        The Payment this Refund was issued against.
      - reasonstring | nullrequired
        The reason the Refund was issued.
        Allowed values: other | other_party_will_pay | overcharged | overpaid | service_not_delivered | null
      - refund_sourcestring | nullrequired
        How the Refund is paid.
        Allowed values: bank_account | deduction_from_balance | payment_account | null
      - statusstring | nullrequired
        The Refund's current status.
        Allowed values: canceled | failed | processing | requires_action | succeeded | null
      - succeeded_atstring | null · date-timerequired
        An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
      - updated_atstring · date-timerequired
        An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
  - statusstring | nullrequired
    The Payment's current status.
    Allowed values: awaiting_authentication | being_processed | canceled | failed | paid | partially_refunded | refunded | scheduled | unpaid | null
  - updated_atstring · date-timerequired
    An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
has_morebooleanrequired
Whether another page is available after next_cursor.
next_cursorstring | nullrequired
The value to pass as cursor for the next page. Null on the last page.
objectanyrequired
Always list.
urlstringrequired
The API path that returned this list.

Example

{
  "object": "list",
  "data":  … ]
     … }
      "id": "947c03a0-35f4-43b4-8df0-60c048915a10",
      "object": "payment",
      "amount": 25000,
      "created_at": "2026-01-01T09:00:00Z",
      "currency": "GBP",
      "internal_notes": "Asked about evening appointments with Dr Smith.",
      "invoice_id": "2fc3a636-66c0-4677-86be-032dd32125e1",
      "links":  … }
        "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678"
      },
      "paid_at": "2026-01-01T09:00:00Z",
      "patient_id": "1a2b3c4d-5e6f-4789-8abc-def012345678",
      "payment_method_type": "bacs_debit",
      "payor_type": "insurance_company",
      "refunds":  … ]
         … }
          "id": "d3d1640d-4d73-43b4-81cb-c0dd11bb3a12",
          "object": "refund",
          "amount": 25000,
          "created_at": "2026-01-01T09:00:00Z",
          "currency": "GBP",
          "error": "The destination payment account declined the refund.",
          "invoice_id": "2fc3a636-66c0-4677-86be-032dd32125e1",
          "links":  … }
            "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678"
          },
          "notes": "Please confirm the appointment by email.",
          "patient_id": "1a2b3c4d-5e6f-4789-8abc-def012345678",
          "payment_id": "947c03a0-35f4-43b4-8df0-60c048915a10",
          "reason": "other",
          "refund_source": "bank_account",
          "status": "canceled",
          "succeeded_at": "2026-01-01T09:00:00Z",
          "updated_at": "2026-01-01T09:00:00Z"
        }
      ],
      "status": "awaiting_authentication",
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/payments"
}

400

A time filter or pagination parameter is invalid.

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

401

The access token is missing, invalid, expired, or revoked.

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

403

The access token lacks the required scope, or the project is disabled.

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

404

The Patient was not found in the Organization.

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

429

Too many requests. Retry after the delay indicated by Retry-After.

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

Request

curl -X GET "https://api.carebit.co/v1/payments" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"

200 response

{
  "object": "list",
  "data":  … ]
     … }
      "id": "947c03a0-35f4-43b4-8df0-60c048915a10",
      "object": "payment",
      "amount": 25000,
      "created_at": "2026-01-01T09:00:00Z",
      "currency": "GBP",
      "internal_notes": "Asked about evening appointments with Dr Smith.",
      "invoice_id": "2fc3a636-66c0-4677-86be-032dd32125e1",
      "links":  … }
        "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678"
      },
      "paid_at": "2026-01-01T09:00:00Z",
      "patient_id": "1a2b3c4d-5e6f-4789-8abc-def012345678",
      "payment_method_type": "bacs_debit",
      "payor_type": "insurance_company",
      "refunds":  … ]
         … }
          "id": "d3d1640d-4d73-43b4-81cb-c0dd11bb3a12",
          "object": "refund",
          "amount": 25000,
          "created_at": "2026-01-01T09:00:00Z",
          "currency": "GBP",
          "error": "The destination payment account declined the refund.",
          "invoice_id": "2fc3a636-66c0-4677-86be-032dd32125e1",
          "links":  … }
            "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678"
          },
          "notes": "Please confirm the appointment by email.",
          "patient_id": "1a2b3c4d-5e6f-4789-8abc-def012345678",
          "payment_id": "947c03a0-35f4-43b4-8df0-60c048915a10",
          "reason": "other",
          "refund_source": "bank_account",
          "status": "canceled",
          "succeeded_at": "2026-01-01T09:00:00Z",
          "updated_at": "2026-01-01T09:00:00Z"
        }
      ],
      "status": "awaiting_authentication",
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/payments"
}

400 response

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

401 response

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

403 response

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

404 response

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

429 response

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

Endpoints

Parameters

Responses