Patient Payment V2
Additive patient payment (or refund with negative amount) by claimControlNumber. Without claimControlNumber, patientId creates an unallocated PATIENT_CASH credit. Caps at ledger paid + remaining PATIENT_AR. paymentTraceId is required; retries return the prior result.
Overview
Additive patient payment API keyed by your claim control number (claim-id / PCN) or patient id (org integration patient identifier). Use this for everyone except ElationbillId posts.
Positive paymentAmount adds to ledger paid (capped at ledger paid + remaining PATIENT_AR). Negative paymentAmount records a refund (floored at $0 paid; notes required). Amount over remaining room creates an unallocated PATIENT_CASH credit.
paymentTraceId is required. Retries with the same org + paymentTraceId return 200 with the prior result (idempotentReplay: true) and do not post again.
For Elation billId absolute-set posts, use Patient Payment.
Use Cases
- Payment Processing Integration: Integrate with payment processors using your claim / patient ids
- EHR Integration: Connect with EHR systems that know claim control numbers
- Partial payments: Post any positive amount less than remaining PATIENT_AR
- Refunds: Post a negative
paymentAmountwithnotes - Unallocated credits: Omit
claimControlNumberand passpatientIdto create wallet credit
Authentication
This endpoint requires JWT access token authentication. First, obtain an access token by calling the/api/token endpoint with your clientId and clientSecret:
Identifiers
claimControlNumber: value of the FHIR Claim identifier with systemhttps://fhir.cairhealth.com/fhir/identifier/claim-id(patient control number / your internal claim id).patientId: value of the Patient identifier whose system is your integration’spatients.patientIdentifierSystem, or Cair’s defaulthttps://fhir.cairhealth.com/fhir/identifier/customer-patient-idwhen none is configured (e.g. cairProfessional).
Request Body
patientId only.claimControlNumber is not provided. Creates an unallocated
patient credit (positive paymentAmount only). Resolved via the org
integration patients.patientIdentifierSystem.notes required).pi_*). Required. Reuse of the same
trace for the same organization returns the prior 200 response without
posting a duplicate.paymentAmount < 0). Optional otherwise.Example Request
Response
Success Response (200)
paymentTraceId include "idempotentReplay": true.
excessAmount / excessCreditId appear only on overpay. refundAmount appears only for refunds.
Error Responses
- 400 — validation errors, missing
paymentTraceId, refund exceeds paid, missing notes on refund, missing patient identifier system - 401 — invalid/missing token
- 404 — claim / patient / organization not found
Payment Processing Logic
- If
paymentTraceIdwas already recorded for this org, return prior result - Resolve claim via
claimControlNumber(or patient viapatientIdfor PATIENT_CASH credit) - Add
paymentAmountto current ledger paid (or subtract for refunds) - Cap positive payments at ledger paid + remaining PATIENT_AR; excess → unallocated PATIENT_CASH
- Sync
PatientPaymentDetails, FHIRPaymentReconciliation, and post DR CASH / CR PATIENT_AR - Refunds append
PatientRefundLogand never create negative claim paid
Related Endpoints
Body
Patient payment information
Non-zero USD amount. Positive = additive payment; negative = refund (notes required).
Required processor transaction id. Same org + trace returns prior 200 without duplicate post.
1Claim control number (claim-id / PCN). Required for claim-targeted payments.
1External patient id. Uses org patients.patientIdentifierSystem when configured; otherwise https://fhir.cairhealth.com/fhir/identifier/customer-patient-id. Required when claimControlNumber is not provided (unallocated credit).
ISO 8601 date string. Defaults to current date if omitted.
Payment method (e.g., Credit Card, Stripe, Check)
Required for refunds (negative paymentAmount).

