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

# List a Patient's Copago Payments

> Every patient-share payment (copago, cuota moderadora, …) collected for one patient at a payer charge, with what is needed to download its receipt

Lists the patient-share payments collected for one patient when a charge was
added to a payer account (EPS, prepagada, póliza): copago, cuota moderadora,
cuota de recuperación and pagos compartidos PVS. Newest first, paginated.

Each row carries the payment `id` used to download its receipt (comprobante de
recaudo, a non-fiscal document) from `GET /api/v1/billing/payments/{id}/receipt`.
Payments made against the patient's own (particular) invoices are not listed
here — see the patient's invoice history.

Requires READ permission on the Billing module. Clinic-wide: no
`X-Location-Id` header, and payments from every location of the clinic are
returned. Every label ships localized to the clinic's locale (`en-US`,
`es-CO`) — display it as-is.

## Path Parameters

<ParamField path="patientId" type="string" required>
  The patient's ID. A patient that does not exist, is inactive or belongs to
  another clinic (or a malformed ID) returns `404`.
</ParamField>

## Query Parameters

<ParamField query="page" type="integer" default="1">
  Page number. Values below 1 or non-numeric fall back to 1; capped at 10000.
</ParamField>

<ParamField query="limit" type="integer" default="20">
  Results per page, clamped to 1–100.
</ParamField>

## Response

<ResponseField name="payments" type="object[]">
  <Expandable title="payment">
    <ResponseField name="id" type="string">Payment ID — use it to download the receipt.</ResponseField>
    <ResponseField name="paymentDate" type="string">ISO 8601 instant the payment was recorded.</ResponseField>
    <ResponseField name="concept" type="string">`copago`, `cuota_moderadora`, `cuota_recuperacion` or `pagos_compartidos_pvs`.</ResponseField>
    <ResponseField name="conceptLabel" type="string">Localized concept.</ResponseField>
    <ResponseField name="amount" type="number">Amount collected, in COP.</ResponseField>
    <ResponseField name="currency" type="string">Always `COP`.</ResponseField>
    <ResponseField name="paymentMethod" type="string">`cash`, `bank_transfer`, `credit_card`, `debit_card`, `check` or `other`.</ResponseField>
    <ResponseField name="paymentMethodLabel" type="string">Localized payment method.</ResponseField>
    <ResponseField name="payerName" type="string | null">The payer billed for the attention; `null` when its account no longer exists.</ResponseField>

    <ResponseField name="payerAccount" type="object | null">
      The payer account the charge landed in; `null` when the account no longer
      exists (its last charge was removed).

      <Expandable title="payerAccount">
        <ResponseField name="id" type="string">Payer account ID.</ResponseField>
        <ResponseField name="number" type="string | null">Electronic invoice (FEV) number once issued; `null` while the account is open.</ResponseField>
        <ResponseField name="period" type="string">`YYYY-MM`.</ResponseField>
        <ResponseField name="periodLabel" type="string">Localized period.</ResponseField>
        <ResponseField name="status" type="string">`open`, `issued` or `filed`.</ResponseField>
        <ResponseField name="statusLabel" type="string">Localized account status.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="serviceDate" type="string | null">`YYYY-MM-DD` date of the attention; `null` when the charge is no longer on its account.</ResponseField>
    <ResponseField name="status" type="string">`pending`, `completed`, `failed`, `cancelled` or `refunded`.</ResponseField>
    <ResponseField name="statusLabel" type="string">Localized payment status.</ResponseField>
    <ResponseField name="receiptAvailable" type="boolean">`true` only for `completed` payments — the receipt endpoint rejects any other status.</ResponseField>

    <ResponseField name="review" type="object | null">
      Present when the charge was removed from its payer account after the
      money was collected. The payment stays listed so the collected money can
      be reviewed.

      <Expandable title="review">
        <ResponseField name="reason" type="string">`charge_removed`, or `other` for a flag this API does not recognize.</ResponseField>
        <ResponseField name="reasonLabel" type="string">Localized reason.</ResponseField>
        <ResponseField name="flaggedAt" type="string | null">ISO 8601 instant the charge was removed.</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  `page`, `limit`, `total`, `totalPages` (at least 1), `hasNext`, `hasPrev`.
</ResponseField>

## Errors

| Status | Code | When |
| :- | :- | :- |
| `401` | `AUTHENTICATION_ERROR` | Missing or expired credentials |
| `403` | `AUTHORIZATION_ERROR` | No READ permission on Billing |
| `404` | `NOT_FOUND_ERROR` | Patient not found in the clinic, inactive, or malformed ID |

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.nevatal.com/api/v1/billing/payments/patient/68c0000000000000000000f1/patient-shares?page=1&limit=20" \
    -H "Authorization: Bearer nvtl_your_api_key"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "data": {
      "payments": [
        {
          "id": "68c0000000000000000000b1",
          "paymentDate": "2026-09-30T22:31:07.991Z",
          "concept": "pagos_compartidos_pvs",
          "conceptLabel": "Shared payment",
          "amount": 99600,
          "currency": "COP",
          "paymentMethod": "cash",
          "paymentMethodLabel": "Cash",
          "payerName": "SURAMERICANA DE SEGUROS DE VIDA SA",
          "payerAccount": {
            "id": "68c0000000000000000000a1",
            "number": null,
            "period": "2026-09",
            "periodLabel": "September 2026",
            "status": "open",
            "statusLabel": "Open"
          },
          "serviceDate": "2026-09-15",
          "status": "completed",
          "statusLabel": "Collected",
          "receiptAvailable": true,
          "review": null
        },
        {
          "id": "68c0000000000000000000b2",
          "paymentDate": "2026-09-15T13:40:37.068Z",
          "concept": "pagos_compartidos_pvs",
          "conceptLabel": "Shared payment",
          "amount": 99600,
          "currency": "COP",
          "paymentMethod": "cash",
          "paymentMethodLabel": "Cash",
          "payerName": "COMPAÑIA DE MEDICINA PREPAGADA COLSANITAS SA",
          "payerAccount": {
            "id": "68c0000000000000000000a2",
            "number": null,
            "period": "2026-09",
            "periodLabel": "September 2026",
            "status": "open",
            "statusLabel": "Open"
          },
          "serviceDate": null,
          "status": "completed",
          "statusLabel": "Collected",
          "receiptAvailable": true,
          "review": {
            "reason": "charge_removed",
            "reasonLabel": "Charge removed from the account — review the collected money",
            "flaggedAt": "2026-09-15T13:41:51.522Z"
          }
        }
      ],
      "pagination": { "page": 1, "limit": 20, "total": 2, "totalPages": 1, "hasNext": false, "hasPrev": false }
    }
  }
  ```

  ```json 404 theme={null}
  {
    "success": false,
    "error": "Patient not found",
    "correlationId": "req-1",
    "code": "NOT_FOUND_ERROR"
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.