Skip to main content
POST
cURL

Overview

Additive patient payment API keyed by claimLifecycleId (or patientFhirId for unallocated credit). Negative paymentAmount records a refund (floored at $0 paid). Overpayments create unallocated patient credits. Self-pay claims also update the patient ledger. This endpoint is temporarily disabled and returns 503 while payment/ledger work continues. For live Elation billId posts, use Patient Payment.

Use Cases

  • Payment Processing Integration: Integrate with payment processors to automatically record patient payments
  • EHR Integration: Connect with EHR systems that know claimLifecycleId
  • Partial payments: Post any positive amount less than remaining PR
  • Refunds: Post a negative paymentAmount with notes
  • Unallocated credits: Omit claimLifecycleId and pass patientFhirId 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:

Request Body

string
Cair claim lifecycle id. Required for claim-targeted payments. Omit when creating an unallocated credit with patientFhirId only.
string
Required when claimLifecycleId is not provided. Creates an unallocated patient credit (positive paymentAmount only).
number
required
Non-zero amount in USD. Positive = additive payment (partial OK). Negative = refund (cannot exceed current 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
Processor transaction id (e.g., Stripe pi_*).
string
Required for refunds (paymentAmount < 0). Optional otherwise.

Example Request

Response

Temporarily Disabled (503)

Success Response (200) — when re-enabled

excessAmount / excessCreditId appear only on overpay. refundAmount appears only for refunds.

Error Responses

  • 400 — validation errors, refund exceeds paid, missing notes on refund
  • 401 — invalid/missing token
  • 404 — claim / organization not found
  • 503 — API temporarily disabled (current)

Payment Processing Logic

  1. Resolve claim via claimLifecycleId
  2. Add paymentAmount to current lifecycle paid (or subtract for refunds)
  3. Cap positive payments at patient responsibility; excess → unallocated PatientCredit
  4. Sync PatientPaymentDetails, FHIR PaymentReconciliation, and (self-pay) ledger
  5. 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).

claimLifecycleId
string

Cair claim lifecycle id. Required for claim-targeted payments.

Minimum string length: 1
patientFhirId
string

Required when claimLifecycleId 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)

paymentTraceId
string

Processor transaction id (e.g., Stripe pi_*)

notes
string

Required for refunds (negative paymentAmount).

Response

Payment or credit processed successfully

success
boolean
required
message
string
required
data
object
required