---
title: "Create patient payment"
method: POST
path: "/api/patient-payments/v4"
tags: ["v4"]
---

# Create patient payment

`POST /api/patient-payments/v4`

Creates a new patient payment record and returns the newly created PatientPayment object.
The allocations can describe whether the payment is being applied toward a specific service line,
claim, or billing provider.

## Headers

- `Authorization` string, required

## Request body

- object
  - `amount_cents` integer, required
  - `payment_timestamp` string, date-time
  - `payment_note` string
  - `patient_external_id` string, required
  - `allocations` TypeFinancialsAllocationCreate[], required
    - `amount_cents` integer, required
    - `target` union, required — Allocation targets describe whether the portion of a payment is being applied toward a specific service line, claim, billing provider, or is unallocated.
      - object
        - `type` 'service_line_by_id', required — Discriminator value: service_line_by_id
        - `value` string, uuid, required
      - object
        - `type` 'claim_by_id', required — Discriminator value: claim_by_id
        - `value` string, uuid, required
      - object
        - `type` 'claim_by_encounter_external_id', required — Discriminator value: claim_by_encounter_external_id
        - `value` string, required
      - object
        - `type` 'billing_provider_by_id', required — Discriminator value: billing_provider_by_id
        - `value` string, uuid, required
      - object
        - `type` 'appointment_by_id_and_patient_external_id', required — Discriminator value: appointment_by_id_and_patient_external_id
        - `appointment_id` string, required
        - `patient_external_id` string, required
      - object
        - `type` 'unattributed', required — Discriminator value: unattributed
    - `earmark` union — If enabled for your organization, defines how a patient prepayment allocation should be earmarked for future auto-allocation. Earmarks hold the allocation until a matching encounter is created, then attempt to allocate to that encounter. Only applicable for unattributed allocations.
      - object — Earmark for auto-allocation to an encounter with this specific date of service
        - `type` 'date_of_service', required — Discriminator value: date_of_service
        - `value` string, required — ISO 8601 date; formatted YYYY-MM-DD (i.e. 2012-02-01)
      - object — Earmark for auto-allocation to an encounter with this specific external ID (more specific than date of service)
        - `type` 'external_encounter_id', required — Discriminator value: external_encounter_id
        - `value` string, required
  - `invoice` string, uuid
  - `payment_method_detail` V4PaymentMethodDetailCreate — unresolved $ref
  - `payment_source` 'MANUAL_ENTRY' | 'PHREESIA' | 'SHERPA_HEALTH' — Allowed payment sources when creating a patient payment via the API.
  - `source_internal_id` string
  - `allocation_restrictions` TypeFinancialsAllocationRestrictionCreate[] — Optional restrictions constraining which claims this payment's credit can be auto-allocated to (e.g. billing provider NPI). Restriction (type, value) pairs must be unique. When omitted, the payment is unrestricted.
    - `restriction_type` 'billing_provider_npi' | 'service_facility_id', required — The dimension along which a payment's auto-allocation can be restricted.
    - `restriction_value` string, required — For billing_provider_npi, the NPI. For service_facility_id, the organization service facility ID.

## Response `200`

Response with status 200

- V4PatientPayment — unresolved $ref

## Other responses

- `403` — Error response with status 403
- `404` — Error response with status 404
- `422` — Error response with status 422

---

[API](https://skmtc.net/joincandidhealth/apis/api-reference.md) · [All operations](https://skmtc.net/joincandidhealth/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/joincandidhealth/api-reference/revisions/7cc5974e4128/schema)