> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.taigabilling.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.taigabilling.com/_mcp/server.

# Creating patient payments

`POST /api/patient-payments/v4` records a payment that has already been collected. It does not charge a card or operate a card reader.

## Supported allocations

Use a single target type for every allocation in a request:

| Target type                                 | Required target fields                  | Use                                   |
| ------------------------------------------- | --------------------------------------- | ------------------------------------- |
| `claim_by_id`                               | `value`: claim UUID                     | Apply a payment to an existing claim. |
| `appointment_by_id_and_patient_external_id` | `appointment_id`, `patient_external_id` | Record an appointment prepayment.     |

Mixing these target types in one request is not supported. `unattributed`, `service_line_by_id`, `claim_by_encounter_external_id`, `billing_provider_by_id`, and unknown or malformed targets are rejected before the payment is created. This restriction applies to this create operation; other financial operations have their own contracts.

## Claim and appointment requirements

For a claim or appointment payment:

* Set `patient_external_id` to the patient’s financial MRN. The patient must belong to your organization.
* Include `allocation_restrictions` with exactly one `billing_provider_npi` restriction whose value is allowed by your credential. Any `service_facility_id` restriction must also be in your scope.
* Supply 1–25 allocations. The payment amount and every allocation amount must be positive integers in cents, and the allocation amounts must total the payment amount.
* Every claim must belong to that patient and be billed under the restricted NPI. Every appointment must belong to the patient, and its target’s `patient_external_id` must match the payment’s value.
* Send only the documented fields. These request bodies, restrictions, allocations, and targets reject unknown fields. In particular, omit `invoice` and allocation `earmark` for claim and appointment payments.

`payment_method_detail` is optional. When provided for a claim or appointment payment, it contains only `payment_method`: `card` with an optional `authorization_number`, `cash`, `check` with `check_number`, or `money_order` with `money_order_serial_number`. Omit the detail or source when absent; do not send `null` for `payment_method_detail` or `payment_source`.

## Minimal claim payment

Replace the example MRN, claim UUID, and billing-provider NPI with values from your organization. This records \$25 already received against one claim.

```json
{
  "amount_cents": 2500,
  "patient_external_id": "PATIENT-123",
  "allocation_restrictions": [
    {
      "restriction_type": "billing_provider_npi",
      "restriction_value": "1234567893"
    }
  ],
  "allocations": [
    {
      "amount_cents": 2500,
      "target": {
        "type": "claim_by_id",
        "value": "11111111-1111-4111-8111-111111111111"
      }
    }
  ]
}
```

## Rejected requests

An unsupported or mixed allocation target, missing or invalid scope restriction, unverified patient, or mismatched claim or appointment is refused with `403` before a payment is created. Claim and appointment requests with unknown fields or invalid shapes are also refused by this gate. A refusal does not confirm whether another organization’s patient or claim exists. Correct the request and verify its [tenant scope](/tenant-scoping) before retrying; payment validation can also return `422`.

## Claim and appointment refunds

`POST /api/patient-refunds/v1` records a refund that has already been returned to the patient. It does not return funds to a card.

Claim and appointment refunds use the same patient, NPI, facility, allocation-count, and amount checks described above. Every allocation in a request must use the same supported target type. Unsupported or mixed targets are refused before creating a refund.

Include `patient_external_id`, `amount_cents`, `allocation_restrictions`, and `allocations`. Optional refund fields are `refund_note`, `refund_reason`, `refund_timestamp`, and `raise_on_overdraft`; these accept `null`. Claim and appointment refunds reject unknown fields, including payment-only fields such as `payment_method_detail` and `payment_note`.

When listing refunds for reconciliation, supply the explicit `patient_external_id` filter. Results are limited to refunds whose ownership or supported allocation targets can be verified within that patient's tenant scope.