Patient Payment

POST

api

webhooks

patient-payment

cURL

curl --request POST \
  --url https://forecaster.cairhealth.com/api/webhooks/patient-payment \
  --header 'Content-Type: application/json' \
  --data '
{
  "billId": "12345",
  "paymentAmount": 150.75,
  "paymentDate": "2024-01-15",
  "paymentMethod": "Credit Card",
  "paymentTraceId": "pi_1234567890"
}
'

import requests

url = "https://forecaster.cairhealth.com/api/webhooks/patient-payment"

payload = {
    "billId": "12345",
    "paymentAmount": 150.75,
    "paymentDate": "2024-01-15",
    "paymentMethod": "Credit Card",
    "paymentTraceId": "pi_1234567890"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    billId: '12345',
    paymentAmount: 150.75,
    paymentDate: '2024-01-15',
    paymentMethod: 'Credit Card',
    paymentTraceId: 'pi_1234567890'
  })
};

fetch('https://forecaster.cairhealth.com/api/webhooks/patient-payment', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://forecaster.cairhealth.com/api/webhooks/patient-payment",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'billId' => '12345',
    'paymentAmount' => 150.75,
    'paymentDate' => '2024-01-15',
    'paymentMethod' => 'Credit Card',
    'paymentTraceId' => 'pi_1234567890'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://forecaster.cairhealth.com/api/webhooks/patient-payment"

	payload := strings.NewReader("{\n  \"billId\": \"12345\",\n  \"paymentAmount\": 150.75,\n  \"paymentDate\": \"2024-01-15\",\n  \"paymentMethod\": \"Credit Card\",\n  \"paymentTraceId\": \"pi_1234567890\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://forecaster.cairhealth.com/api/webhooks/patient-payment")
  .header("Content-Type", "application/json")
  .body("{\n  \"billId\": \"12345\",\n  \"paymentAmount\": 150.75,\n  \"paymentDate\": \"2024-01-15\",\n  \"paymentMethod\": \"Credit Card\",\n  \"paymentTraceId\": \"pi_1234567890\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://forecaster.cairhealth.com/api/webhooks/patient-payment")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"billId\": \"12345\",\n  \"paymentAmount\": 150.75,\n  \"paymentDate\": \"2024-01-15\",\n  \"paymentMethod\": \"Credit Card\",\n  \"paymentTraceId\": \"pi_1234567890\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "message": "Payment processed successfully",
  "data": {
    "claimId": "550e8400-e29b-41d4-a716-446655440000",
    "claimLifecycleId": "lifecycle-12345",
    "amountSetOnClaim": 150.75,
    "excessAmount": 0
  }
}

Overview

Elation-specific webhook for posting patient payments by billId (Elation bill.id). Payments use absolute-set semantics: paymentAmount is the new paid total on the claim. The amount applied to the claim is capped at ledger paid + remaining PATIENT_AR. Anything above that remaining room is an unallocated PATIENT_CASH credit — including posts before a remit TRANSFER_TO_PATIENT (when PATIENT_AR is still $0). For additive claimLifecycleId / refund posts (everyone else), use Patient Payment V2.

Use Cases

Payment Processing Integration: Integrate with payment processors (Stripe, Square, etc.) to automatically record patient payments
EHR Integration: Connect with EHR systems like Elation to sync patient payment data via billId
Automated Payment Recording: Automatically update claims when payments are received through external systems

Authentication

This endpoint requires JWT access token authentication, consistent with all other public API endpoints. First, obtain an access token by calling the /api/token endpoint with your clientId and clientSecret:

curl -X POST https://forecaster.cairhealth.com/api/token \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "your-client-id",
    "clientSecret": "your-client-secret"
  }'

Then include the access token in the Authorization header:

Authorization: Bearer <accessToken>

Your clientId and clientSecret can be found in your admin panel.

Request Body

string

required

The Elation bill.id that maps to the Claim identifier. This should match the Claim identifier with system https://fhir.cairhealth.com/fhir/identifier/claim-id.

number

required

The payment amount in USD. Must be a positive number. Interpreted as the absolute paid total to set on the claim (capped at ledger remaining room).

string

The date of the payment in ISO 8601 format (e.g., “2024-01-15” or “2024-01-15T10:30:00Z”). If not provided, defaults to the current date.

string

The method of payment (e.g., “Credit Card”, “Debit Card”, “Stripe”, “Check”, “Cash”).

string

The transaction ID or payment intent ID from the payment processor (e.g., Stripe payment intent ID like “pi_1234567890”).

Example Request

# First, get an access token
TOKEN_RESPONSE=$(curl -X POST https://forecaster.cairhealth.com/api/token \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "your-client-id",
    "clientSecret": "your-client-secret"
  }')

ACCESS_TOKEN=$(echo $TOKEN_RESPONSE | jq -r '.accessToken')

# Then use the access token to call the webhook
curl -X POST https://forecaster.cairhealth.com/api/webhooks/patient-payment \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "billId": "12345",
    "paymentAmount": 150.75,
    "paymentDate": "2024-01-15",
    "paymentMethod": "Credit Card",
    "paymentTraceId": "pi_1234567890"
  }'

Response

Success Response (200)

{
  "success": true,
  "message": "Payment processed successfully",
  "data": {
    "claimId": "550e8400-e29b-41d4-a716-446655440000",
    "claimLifecycleId": "lifecycle-12345",
    "amountSetOnClaim": 150.75,
    "excessAmount": 10.0,
    "ledgerPosted": true,
    "ledgerEventKey": "pi_1234567890:150.75"
  }
}

excessAmount is only present when the payment exceeds remaining PATIENT_AR. ledgerPosted is true when a CASH / PATIENT_AR (or refund) event was written.

Error Responses

400 — invalid body or missing required fields
401 — invalid/missing token
404 — claim not found for billId
500 — unexpected error during payment processing

Payment Processing Logic

Claim Lookup: Search for a claim matching billId via identifier system https://fhir.cairhealth.com/fhir/identifier/claim-id.
Ledger cap: Max on-claim paid = current ledger paid + max(0, PATIENT_AR). Remaining room of $0 (including pre-drop) sends the full amount to PATIENT_CASH.
Absolute apply: Set on-claim paid to min(paymentAmount, cap); excess → unallocated PatientCredit + PATIENT_CASH.
Persist: Update PatientPaymentDetails, FHIR PaymentReconciliation, and post DR CASH / CR PATIENT_AR for the applied delta.

Body

application/json

Patient payment information

billId

string

required

Elation bill.id that maps to Claim.identifier with system 'https://fhir.cairhealth.com/fhir/identifier/claim-id'

Minimum string length: 1

paymentAmount

number

required

Payment amount in USD

Required range: x > 0

paymentDate

string<date>

ISO 8601 date string (e.g., '2024-01-15'). Defaults to current date if not provided.

paymentMethod

string

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

paymentTraceId

string

Stripe payment intent ID or transaction ID (e.g., 'pi_1234567890')

Response

Payment processed successfully

success

boolean

required

Indicates whether the payment was processed successfully

message

string

required

Success message

data

object

required

Show child attributes

cURL

curl --request POST \
  --url https://forecaster.cairhealth.com/api/webhooks/patient-payment \
  --header 'Content-Type: application/json' \
  --data '
{
  "billId": "12345",
  "paymentAmount": 150.75,
  "paymentDate": "2024-01-15",
  "paymentMethod": "Credit Card",
  "paymentTraceId": "pi_1234567890"
}
'

import requests

url = "https://forecaster.cairhealth.com/api/webhooks/patient-payment"

payload = {
    "billId": "12345",
    "paymentAmount": 150.75,
    "paymentDate": "2024-01-15",
    "paymentMethod": "Credit Card",
    "paymentTraceId": "pi_1234567890"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    billId: '12345',
    paymentAmount: 150.75,
    paymentDate: '2024-01-15',
    paymentMethod: 'Credit Card',
    paymentTraceId: 'pi_1234567890'
  })
};

fetch('https://forecaster.cairhealth.com/api/webhooks/patient-payment', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://forecaster.cairhealth.com/api/webhooks/patient-payment",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'billId' => '12345',
    'paymentAmount' => 150.75,
    'paymentDate' => '2024-01-15',
    'paymentMethod' => 'Credit Card',
    'paymentTraceId' => 'pi_1234567890'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://forecaster.cairhealth.com/api/webhooks/patient-payment"

	payload := strings.NewReader("{\n  \"billId\": \"12345\",\n  \"paymentAmount\": 150.75,\n  \"paymentDate\": \"2024-01-15\",\n  \"paymentMethod\": \"Credit Card\",\n  \"paymentTraceId\": \"pi_1234567890\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://forecaster.cairhealth.com/api/webhooks/patient-payment")
  .header("Content-Type", "application/json")
  .body("{\n  \"billId\": \"12345\",\n  \"paymentAmount\": 150.75,\n  \"paymentDate\": \"2024-01-15\",\n  \"paymentMethod\": \"Credit Card\",\n  \"paymentTraceId\": \"pi_1234567890\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://forecaster.cairhealth.com/api/webhooks/patient-payment")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"billId\": \"12345\",\n  \"paymentAmount\": 150.75,\n  \"paymentDate\": \"2024-01-15\",\n  \"paymentMethod\": \"Credit Card\",\n  \"paymentTraceId\": \"pi_1234567890\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "message": "Payment processed successfully",
  "data": {
    "claimId": "550e8400-e29b-41d4-a716-446655440000",
    "claimLifecycleId": "lifecycle-12345",
    "amountSetOnClaim": 150.75,
    "excessAmount": 0
  }
}

Overview

API Authentication

Eligibility

Enrollments/Providers

Claims

Claim AI Actions

Patient Chart Analysis

Patient Payments

Webhooks

AI Phone Calls

Overview

Use Cases

Authentication

Request Body

Example Request

Response

Success Response (200)

Error Responses

Payment Processing Logic

Body

Response

​Overview

​Use Cases

​Authentication

​Request Body

​Example Request

​Response

​Success Response (200)

​Error Responses

​Payment Processing Logic

​Related Endpoints

Body

Response

Overview

Use Cases

Authentication

Request Body

Example Request

Response

Success Response (200)

Error Responses

Payment Processing Logic

Related Endpoints