Skip to main content
POST
cURL

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 Elation billId 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 paymentAmount with notes
  • Unallocated credits: Omit claimControlNumber and pass patientId to 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:
Then include the access token in the Authorization header:

Identifiers

  • claimControlNumber: value of the FHIR Claim identifier with system https://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’s patients.patientIdentifierSystem, or Cair’s default https://fhir.cairhealth.com/fhir/identifier/customer-patient-id when none is configured (e.g. cairProfessional).

Request Body

string
Your claim control number (claim-id). Required for claim-targeted payments. Omit when creating an unallocated credit with patientId only.
string
Required when claimControlNumber is not provided. Creates an unallocated patient credit (positive paymentAmount only). Resolved via the org integration patients.patientIdentifierSystem.
number
required
Non-zero amount in USD. Positive = additive payment (partial OK). Negative = refund (cannot exceed current ledger paid; notes required).
string
ISO 8601 date string. Defaults to the current date when omitted.
string
Payment method (e.g., “Credit Card”, “Stripe”, “Check”).
string
required
Processor transaction id (e.g., Stripe pi_*). Required. Reuse of the same trace for the same organization returns the prior 200 response without posting a duplicate.
string
Required for refunds (paymentAmount < 0). Optional otherwise.

Example Request

Response

Success Response (200)

Retries with the same 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

  1. If paymentTraceId was already recorded for this org, return prior result
  2. Resolve claim via claimControlNumber (or patient via patientId for PATIENT_CASH credit)
  3. Add paymentAmount to current ledger paid (or subtract for refunds)
  4. Cap positive payments at ledger paid + remaining PATIENT_AR; excess → unallocated PATIENT_CASH
  5. Sync PatientPaymentDetails, FHIR PaymentReconciliation, and post DR CASH / CR PATIENT_AR
  6. Refunds append PatientRefundLog and never create negative claim paid

Body

application/json

Patient payment information

paymentAmount
number
required

Non-zero USD amount. Positive = additive payment; negative = refund (notes required).

paymentTraceId
string
required

Required processor transaction id. Same org + trace returns prior 200 without duplicate post.

Minimum string length: 1
claimControlNumber
string

Claim control number (claim-id / PCN). Required for claim-targeted payments.

Minimum string length: 1
patientId
string

External 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).

paymentDate
string<date>

ISO 8601 date string. Defaults to current date if omitted.

paymentMethod
string

Payment method (e.g., Credit Card, Stripe, Check)

notes
string

Required for refunds (negative paymentAmount).

Response

Payment or credit processed successfully (or idempotent replay)

success
boolean
required
message
string
required
data
object
required
idempotentReplay
boolean