---
title: "POST /api/webhooks/patient-payment-v2"
method: POST
path: "/api/webhooks/patient-payment-v2"
---

# POST /api/webhooks/patient-payment-v2

`POST /api/webhooks/patient-payment-v2`

## Request

- Base URL: `https://forecaster.cairhealth.com`
- URL: `https://forecaster.cairhealth.com/api/webhooks/patient-payment-v2`
- Auth: none required

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.

## Request body

- object
  - `claimControlNumber` string: Claim control number (claim-id / PCN). Required for claim-targeted payments.
  - `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).
  - `paymentAmount` number, required: Non-zero USD amount. Positive = additive payment; negative = refund (notes required).
  - `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, required: Required processor transaction id. Same org + trace returns prior 200 without duplicate post.
  - `notes` string: Required for refunds (negative paymentAmount).

## Response `200`

Payment or credit processed successfully (or idempotent replay)

- object
  - `success` boolean, required
  - `message` string, required
  - `idempotentReplay` boolean
  - `data` object, required
    - `claimId` string
    - `claimLifecycleId` string
    - `claimControlNumber` string
    - `amountSetOnClaim` number
    - `previousPaid` number
    - `excessAmount` number
    - `excessCreditId` string
    - `refundAmount` number
    - `creditId` string
    - `patientFhirId` string
    - `paymentAmount` number
    - `paymentTraceId` string

## Other responses

- `400`: Invalid request body
- `401`: Unauthorized
- `404`: Claim or organization not found

## Changes

- **2026-11-03** `b32380ccde9a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/cairhealth/apis/cair-health-apis/changes/api/webhooks/patient-payment-v2/post.md)

---

[API](https://skmtc.dev/cairhealth/apis/cair-health-apis.md) - [All operations](https://skmtc.dev/cairhealth/apis/cair-health-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/cairhealth/apis/cair-health-apis/revisions/b32380ccde9a?raw)