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:

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.

{
  "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 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.