> 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. # Create patient payment POST https://api.taigabilling.com/api/patient-payments/v4 Content-Type: application/json Records an already-collected patient payment. Each request may contain only claim_by_id allocations or only appointment_by_id_and_patient_external_id allocations; mixed target types are rejected. unattributed, service_line_by_id, claim_by_encounter_external_id, billing_provider_by_id, and malformed targets are unsupported. Claim and appointment payments require 1–25 positive allocations, a verified financial patient MRN, and exactly one in-scope billing_provider_npi allocation restriction; any service_facility_id restriction must also be in scope. Each claim must match both the patient and restricted NPI; every appointment must belong to the patient. For claim and appointment payments, unknown fields and invalid scope or target proofs are refused with 403 before creating a payment. See [Creating patient payments](/patient-payments) for requirements and a minimal request. Reference: https://docs.taigabilling.com/api-reference/patient-payments-v-4/patient-payments-v-4-create ## Authentication - `Authorization` header (bearer token, required) — Send your Taiga API key as a Bearer token. Create and manage keys in the Taiga developer portal. ## Servers - `https://api.taigabilling.com` (Production, default) - `https://api-staging.taigabilling.com` (Staging) ## Request ### Body (application/json) This endpoint expects a PatientPaymentsV4_patientPayments_v4_create_Request. - `PatientPaymentsV4_patientPayments_v4_create_Request` - Claim payment: Claim payment - Appointment payment: Appointment payment ## Response ### 200 - `patient_payment_id` (string, required) - `organization_id` (string, required) - `payment_source` (enum, required) - Allowed values: `MANUAL_ENTRY`, `CHARGEBEE`, `SQUARE`, `STRIPE`, `ELATION`, `CEDAR`, `HEALTHIE`, `REALLOCATION`, `PHREESIA`, `INSTAMED`, `SHERPA_HEALTH`, `LOCKBOX` - `amount_cents` (integer, required) - `patient_external_id` (string, required) - `allocations` (list of Allocation, required) - `source_internal_id` (string, optional, nullable) - `payment_timestamp` (datetime, optional, nullable) - `payment_note` (string, optional, nullable) - `invoice` (string, optional, nullable) - `payment_method_detail` (patient-paymentsv4PaymentMethodDetail, optional, nullable) ## Errors ### 403 Forbidden Error The payment was refused before creation: an allocation target is unsupported or mixed with another target type, or a claim/appointment request has an invalid shape, lacks its required in-scope billing-provider restriction, or references a patient, claim, appointment, or facility that could not be verified in scope. - `PatientPayments_v4_createRequestForbiddenError` - PatientPaymentsV4CreateRequestForbiddenError0 ### 404 Not Found Error - `PatientPayments_v4_createRequestNotFoundError` - PatientPaymentsV4CreateRequestNotFoundError0 ### 422 Unprocessable Entity Error - `PatientPayments_v4_createRequestUnprocessableEntityError` - PatientPaymentsV4CreateRequestUnprocessableEntityError0 ## Types ### Claim payment - `allocation_restrictions` (list of ApiPatientPaymentsV4PostRequestBodyContentApplicationJsonSchemaOneOf0AllocationRestrictionsItems, required) — Required for claim and appointment allocations. Include exactly one billing_provider_npi restriction in your credential's allowlist. Every service_facility_id restriction must also be in scope. Each claim must match the restricted NPI and the payment's patient_external_id. - `allocations` (list of ApiPatientPaymentsV4PostRequestBodyContentApplicationJsonSchemaOneOf0AllocationsItems, required) - `amount_cents` (integer, required) - `patient_external_id` (string, required) - `payment_method_detail` (ApiPatientPaymentsV4PostRequestBodyContentApplicationJsonSchemaOneOf0PaymentMethodDetail, optional) - `payment_note` (string, optional, nullable) - `payment_source` (enum, optional) — Allowed payment sources when creating a patient payment via the API. - Allowed values: `MANUAL_ENTRY`, `PHREESIA`, `SHERPA_HEALTH`, `LOCKBOX` - `payment_timestamp` (datetime, optional, nullable) - `source_internal_id` (string, optional, nullable) ### Appointment payment - `allocation_restrictions` (list of ApiPatientPaymentsV4PostRequestBodyContentApplicationJsonSchemaOneOf1AllocationRestrictionsItems, required) — Required for claim and appointment allocations. Include exactly one billing_provider_npi restriction in your credential's allowlist. Every service_facility_id restriction must also be in scope. Each claim must match the restricted NPI and the payment's patient_external_id. - `allocations` (list of ApiPatientPaymentsV4PostRequestBodyContentApplicationJsonSchemaOneOf1AllocationsItems, required) - `amount_cents` (integer, required) - `patient_external_id` (string, required) - `payment_method_detail` (ApiPatientPaymentsV4PostRequestBodyContentApplicationJsonSchemaOneOf1PaymentMethodDetail, optional) - `payment_note` (string, optional, nullable) - `payment_source` (enum, optional) — Allowed payment sources when creating a patient payment via the API. - Allowed values: `MANUAL_ENTRY`, `PHREESIA`, `SHERPA_HEALTH`, `LOCKBOX` - `payment_timestamp` (datetime, optional, nullable) - `source_internal_id` (string, optional, nullable) ### Allocation - `amount_cents` (integer, required) - `target` (AllocationTarget, required) — Allocation targets describe whether the portion of a payment is being applied toward a specific service line, claim, billing provider, or is unallocated. - `allocation_id` (string, optional, nullable) - `earmark` (BalanceEarmark, optional, nullable) — The active earmark created by this allocation, if any. Only present when this allocation created an earmark for future auto-allocation and the earmark has not been deleted. - `allocated_on` (datetime, optional, nullable) ### patient-paymentsv4PaymentMethodDetail - `payment_method` (patient-paymentsv4PaymentMethod, required) - `collected_at_address` (StreetAddressShortZip, optional, nullable) - `provider_info` (patient-paymentsv4PaymentMethodProviderInfo, optional, nullable) ### PatientPaymentsV4CreateRequestForbiddenError0 - `errorName` (enum, optional) - Allowed values: `UnprocessableEntityError` - `content` (UnauthorizedErrorMessage, optional) ### PatientPaymentsV4CreateRequestNotFoundError0 - `errorName` (enum, optional) - Allowed values: `UnprocessableEntityError` - `content` (EntityNotFoundErrorMessage, optional) ### PatientPaymentsV4CreateRequestUnprocessableEntityError0 - `errorName` (enum, optional) - Allowed values: `UnprocessableEntityError` - `content` (UnprocessableEntityErrorMessage, optional) ### ApiPatientPaymentsV4PostRequestBodyContentApplicationJsonSchemaOneOf0AllocationRestrictionsItems - `restriction_type` (enum, required) - Allowed values: `billing_provider_npi`, `service_facility_id` - `restriction_value` (string, required) ### ApiPatientPaymentsV4PostRequestBodyContentApplicationJsonSchemaOneOf0AllocationsItems - `amount_cents` (integer, required) - `target` (ApiPatientPaymentsV4PostRequestBodyContentApplicationJsonSchemaOneOf0AllocationsItemsTarget, required) ### ApiPatientPaymentsV4PostRequestBodyContentApplicationJsonSchemaOneOf0PaymentMethodDetail - `payment_method` (ApiPatientPaymentsV4PostRequestBodyContentApplicationJsonSchemaOneOf0PaymentMethodDetailPaymentMethod, required) ### ApiPatientPaymentsV4PostRequestBodyContentApplicationJsonSchemaOneOf1AllocationRestrictionsItems - `restriction_type` (enum, required) - Allowed values: `billing_provider_npi`, `service_facility_id` - `restriction_value` (string, required) ### ApiPatientPaymentsV4PostRequestBodyContentApplicationJsonSchemaOneOf1AllocationsItems - `amount_cents` (integer, required) - `target` (ApiPatientPaymentsV4PostRequestBodyContentApplicationJsonSchemaOneOf1AllocationsItemsTarget, required) ### ApiPatientPaymentsV4PostRequestBodyContentApplicationJsonSchemaOneOf1PaymentMethodDetail - `payment_method` (ApiPatientPaymentsV4PostRequestBodyContentApplicationJsonSchemaOneOf1PaymentMethodDetailPaymentMethod, required) ### AllocationTarget Allocation targets describe whether the portion of a payment is being applied toward a specific service line, claim, billing provider, or is unallocated. - AllocationTarget0 - AllocationTarget1 - AllocationTarget2 - AllocationTarget3 - AllocationTarget4 ### BalanceEarmark Represents an active balance earmarking record that holds allocated funds for future auto-allocation. Earmarks are created when funds are allocated but should be held for a specific encounter or date of service. Only active (non-deleted) earmarks are returned. - `id` (string, required) - `target` (AllocationEarmarkType, required) — The target for this earmark (date of service or external encounter ID) - `amount_earmarked_cents` (integer, optional, nullable) — The amount earmarked in cents for future allocation - `created_by_allocation_id` (string, optional, nullable) — The ID of the allocation that created this earmark ### patient-paymentsv4PaymentMethod - PatientPaymentsv4PaymentMethod0 - PatientPaymentsv4PaymentMethod1 - PatientPaymentsv4PaymentMethod2 - PatientPaymentsv4PaymentMethod3 ### StreetAddressShortZip - `address1` (string, required) - `city` (string, required) - `state` (enum, required) - Allowed values: `AA`, `AE`, `AP`, `AL`, `AK`, `AS`, `AZ`, `AR`, `CA`, `CO`, `CT`, `DC`, `DE`, `FL`, `FM`, `GA`, `GU`, `HI`, `ID`, `IL`, `IN`, `IA`, `KS`, `KY`, `LA`, `ME`, `MD`, `MA`, `MH`, `MI`, `MN`, `MP`, `MS`, `MO`, `MT`, `NE`, `NV`, `NH`, `NJ`, `NM`, `NY`, `NC`, `ND`, `OH`, `OK`, `OR`, `PA`, `PR`, `PW`, `RI`, `SC`, `SD`, `TN`, `TX`, `UT`, `VI`, `VT`, `VA`, `WA`, `WV`, `WI`, `WY`, `FC` - `zip_code` (string, required) — 5-digit zip code - `address2` (string, optional, nullable) - `zip_plus_four_code` (string, optional, nullable) — 4-digit zip add-on code https://en.wikipedia.org/wiki/ZIP_Code#ZIP+4 ### patient-paymentsv4PaymentMethodProviderInfo - `npi` (string, optional, nullable) - `first_name` (string, optional, nullable) - `last_name` (string, optional, nullable) ### UnauthorizedErrorMessage - `message` (string, optional, nullable) ### EntityNotFoundErrorMessage - `id` (string, required) ### UnprocessableEntityErrorMessage - `message` (string, optional, nullable) ### ApiPatientPaymentsV4PostRequestBodyContentApplicationJsonSchemaOneOf0AllocationsItemsTarget - `type` (enum, required) - Allowed values: `claim_by_id` - `value` (string, required) ### ApiPatientPaymentsV4PostRequestBodyContentApplicationJsonSchemaOneOf0PaymentMethodDetailPaymentMethod - ApiPatientPaymentsV4PostRequestBodyContentApplicationJsonSchemaOneOf0PaymentMethodDetailPaymentMethod0 - ApiPatientPaymentsV4PostRequestBodyContentApplicationJsonSchemaOneOf0PaymentMethodDetailPaymentMethod1 - ApiPatientPaymentsV4PostRequestBodyContentApplicationJsonSchemaOneOf0PaymentMethodDetailPaymentMethod2 - ApiPatientPaymentsV4PostRequestBodyContentApplicationJsonSchemaOneOf0PaymentMethodDetailPaymentMethod3 ### ApiPatientPaymentsV4PostRequestBodyContentApplicationJsonSchemaOneOf1AllocationsItemsTarget - `appointment_id` (string, required) - `patient_external_id` (string, required) - `type` (enum, required) - Allowed values: `appointment_by_id_and_patient_external_id` ### ApiPatientPaymentsV4PostRequestBodyContentApplicationJsonSchemaOneOf1PaymentMethodDetailPaymentMethod - ApiPatientPaymentsV4PostRequestBodyContentApplicationJsonSchemaOneOf1PaymentMethodDetailPaymentMethod0 - ApiPatientPaymentsV4PostRequestBodyContentApplicationJsonSchemaOneOf1PaymentMethodDetailPaymentMethod1 - ApiPatientPaymentsV4PostRequestBodyContentApplicationJsonSchemaOneOf1PaymentMethodDetailPaymentMethod2 - ApiPatientPaymentsV4PostRequestBodyContentApplicationJsonSchemaOneOf1PaymentMethodDetailPaymentMethod3 ### AllocationTarget0 - `claim_id` (string, required) - `encounter_id` (string, required) - `service_line_id` (string, required) - `type` (enum, required) - Allowed values: `service_line` ### AllocationTarget1 - `claim_id` (string, required) - `encounter_id` (string, required) - `type` (enum, required) - Allowed values: `claim` ### AllocationTarget2 - `billing_provider_id` (string, required) - `type` (enum, required) - Allowed values: `billing_provider_id` ### AllocationTarget3 - `appointment_id` (string, required) - `patient_external_id` (string, required) - `type` (enum, required) - Allowed values: `appointment` ### AllocationTarget4 - `type` (enum, required) - Allowed values: `unattributed` ### AllocationEarmarkType 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. - AllocationEarmarkType0 - AllocationEarmarkType1 ### PatientPaymentsv4PaymentMethod0 - `type` (enum, required) - Allowed values: `cash` ### PatientPaymentsv4PaymentMethod1 - `check_number` (string, required) - `type` (enum, required) - Allowed values: `check` ### PatientPaymentsv4PaymentMethod2 - `type` (enum, required) - Allowed values: `card` - `authorization_number` (string, optional, nullable) ### PatientPaymentsv4PaymentMethod3 - `money_order_serial_number` (string, required) - `type` (enum, required) - Allowed values: `money_order` ### ApiPatientPaymentsV4PostRequestBodyContentApplicationJsonSchemaOneOf0PaymentMethodDetailPaymentMethod0 - `type` (enum, required) - Allowed values: `card` - `authorization_number` (string, optional, nullable) ### ApiPatientPaymentsV4PostRequestBodyContentApplicationJsonSchemaOneOf0PaymentMethodDetailPaymentMethod1 - `type` (enum, required) - Allowed values: `cash` ### ApiPatientPaymentsV4PostRequestBodyContentApplicationJsonSchemaOneOf0PaymentMethodDetailPaymentMethod2 - `check_number` (string, required) - `type` (enum, required) - Allowed values: `check` ### ApiPatientPaymentsV4PostRequestBodyContentApplicationJsonSchemaOneOf0PaymentMethodDetailPaymentMethod3 - `money_order_serial_number` (string, required) - `type` (enum, required) - Allowed values: `money_order` ### ApiPatientPaymentsV4PostRequestBodyContentApplicationJsonSchemaOneOf1PaymentMethodDetailPaymentMethod0 - `type` (enum, required) - Allowed values: `card` - `authorization_number` (string, optional, nullable) ### ApiPatientPaymentsV4PostRequestBodyContentApplicationJsonSchemaOneOf1PaymentMethodDetailPaymentMethod1 - `type` (enum, required) - Allowed values: `cash` ### ApiPatientPaymentsV4PostRequestBodyContentApplicationJsonSchemaOneOf1PaymentMethodDetailPaymentMethod2 - `check_number` (string, required) - `type` (enum, required) - Allowed values: `check` ### ApiPatientPaymentsV4PostRequestBodyContentApplicationJsonSchemaOneOf1PaymentMethodDetailPaymentMethod3 - `money_order_serial_number` (string, required) - `type` (enum, required) - Allowed values: `money_order` ### AllocationEarmarkType0 - `type` (enum, required) - Allowed values: `date_of_service` - `value` (string, optional) — ISO 8601 date; formatted YYYY-MM-DD (i.e. 2012-02-01) ### AllocationEarmarkType1 - `type` (enum, required) - Allowed values: `external_encounter_id` - `value` (string, optional) ## Examples **Request** ```json { "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" } } ], "amount_cents": 2500, "patient_external_id": "PATIENT-123" } ``` **Response** ```json { "patient_payment_id": "string", "organization_id": "string", "payment_source": "MANUAL_ENTRY", "amount_cents": 1, "patient_external_id": "string", "allocations": [ { "amount_cents": 1, "target": { "claim_id": "string", "encounter_id": "string", "service_line_id": "string", "type": "service_line" }, "allocation_id": "string", "earmark": { "id": "string", "target": { "type": "date_of_service", "value": "string" }, "amount_earmarked_cents": 1, "created_by_allocation_id": "string" }, "allocated_on": "2024-01-15T09:30:00Z" } ], "source_internal_id": "string", "payment_timestamp": "2024-01-15T09:30:00Z", "payment_note": "string", "invoice": "string", "payment_method_detail": { "payment_method": { "type": "cash" }, "collected_at_address": { "address1": "string", "city": "string", "state": "AA", "zip_code": "string", "address2": "string", "zip_plus_four_code": "string" }, "provider_info": { "npi": "string", "first_name": "string", "last_name": "string" } } } ``` **SDK Code** ```python PatientPaymentsV4_patientPayments_v4_create_example import requests url = "https://api.taigabilling.com/api/patient-payments/v4" payload = { "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" } } ], "amount_cents": 2500, "patient_external_id": "PATIENT-123" } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ```