Case Payments

POST/api/v1/cases/:caseId/payments

Creates a payment record for a case. Supports three modes: create an unpaid record, preauthorize via Stripe, or immediately charge the patient's card on file.

cv-api-key

Productionhttps://api.care360-next.carevalidate.com/api/v1/cases/:caseId/payments

Staginghttps://api-staging.care360-next.carevalidate.com/api/v1/cases/:caseId/payments

Path Parameters

caseIdstringrequired

The case identifier (UUID v4).

Example: 9f0f2f70-f536-4b1d-8ed4-c831f4a4bcab

Request Body

Body Parameters

amountnumberrequired

Payment amount. Must be a positive number.

Example: 100

descriptionstringrequired

Payment description.

Example: Refill for medication

capturebooleanoptional

When true, immediately charges the case submitter's default payment method on file. Cannot be combined with preauthorize. Defaults to false.

Example: true

preauthorizebooleanoptional

When true, places a hold on the patient's card via Stripe without charging it. The hold can be captured later. Cannot be combined with capture. Defaults to false.

Example: true

productIdstringoptional

Optional product identifier (UUID v4).

Example: 0d8b6f56-4f10-4b68-89c5-cf6593f74c0f

statusstringoptional

Payment status. Defaults to UNPAID.

Example: UNPAID

idempotencyKeystringoptional

Optional unique key to prevent duplicate payment creation. Scoped per organization. Subsequent requests with the same key return the original payment without re-charging.

Example: case-payment-unique-key-001

applyPromoCodebooleanoptional

When true, applies the promo code already attached to the case (if any and not exhausted) before the preauthorization or charge, discounting the amount and recording the promo code on the payment. `amount` must still be the full, pre-discount amount — do not apply the discount yourself before sending the request, or it will be discounted twice. Has no effect when the case has no promo code attached, the code is exhausted, or neither capture nor preauthorize is set. Defaults to false.

Example: true

Workflow Behavior

capture	preauthorize	Result
false (default)	false (default)	Creates an UNPAID payment record. No charge or hold.
false	true	Places a Stripe hold for the amount. Status is UNPAID until the hold is captured.
true	false	Charges the patient's default card on file immediately. Returns PAID on success.

When applyPromoCode: true is combined with capture or preauthorize, and the case has a valid, non-exhausted promo code attached, the discounted amount is what's preauthorized/charged — the amount in the response and the stored payment reflect the post-discount total, not the amount submitted in the request.

Response Fields

Field	Type	Description
success	boolean	Indicates if the request was successful
message	string	Success or error message
data.result.paymentId	string	Unique identifier of the created case payment
data.result.status	string	Payment status — UNPAID or PAID
data.result.amount	number | string	Payment amount
data.result.description	string	Payment description
data.result.createdAt	string	Payment creation timestamp (ISO 8601)
data.result.transactionDate	string	Timestamp when the charge settled. Only present when capture: true.
error	string	Detailed error message (only on failure)
code	string	Machine-readable error code (only on failure)

Request Examples

cURL — Capture

curl -X POST "https://api.care360-next.carevalidate.com/api/v1/cases/9f0f2f70-f536-4b1d-8ed4-c831f4a4bcab/payments" \
-H "cv-api-key: YOUR_SECRET_KEY_HERE" \
-H "Content-Type: application/json" \
-d '{
  "amount": 100.00,
  "description": "Refill for medication",
  "capture": true,
  "idempotencyKey": "refill-2026-06-30-case-001"
}'

cURL — Unpaid

curl -X POST "https://api.care360-next.carevalidate.com/api/v1/cases/9f0f2f70-f536-4b1d-8ed4-c831f4a4bcab/payments" \
-H "cv-api-key: YOUR_SECRET_KEY_HERE" \
-H "Content-Type: application/json" \
-d '{
  "amount": 100.00,
  "status": "UNPAID",
  "preauthorize": true,
  "description": "Creating preauthorized payment for DEMO"
}'

JavaScript

const caseId = "9f0f2f70-f536-4b1d-8ed4-c831f4a4bcab";
const response = await fetch(
`https://api.care360-next.carevalidate.com/api/v1/cases/${caseId}/payments`,
{
  method: "POST",
  headers: {
    "cv-api-key": "YOUR_SECRET_KEY_HERE",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: 100.0,
    status: "UNPAID",
    preauthorize: true,
    description: "Creating preauthorized payment for DEMO",
  }),
}
);

const data = await response.json();
console.log(data);

Python

import requests

case_id = "9f0f2f70-f536-4b1d-8ed4-c831f4a4bcab"
response = requests.post(
  f"https://api.care360-next.carevalidate.com/api/v1/cases/{case_id}/payments",
  headers={
      "cv-api-key": "YOUR_SECRET_KEY_HERE",
      "Content-Type": "application/json",
  },
  json={
      "amount": 100.00,
      "description": "Refill for medication",
      "capture": True,
      "idempotencyKey": "refill-2026-06-30-case-001",
  },
)

data = response.json()
print(data)

Responses

▶200CapturedPayment created and charged successfully.

{
  "success": true,
  "message": "Case payment created successfully",
  "data": {
    "result": {
      "paymentId": "9d2461f0-54b8-43dd-9507-e3143d4a50a1",
      "status": "PAID",
      "amount": "100.00",
      "description": "Refill for medication",
      "createdAt": "2026-06-30T12:00:00.000Z",
      "transactionDate": "2026-06-30T12:00:01.000Z"
    }
  }
}

▶200UnpaidPayment record created without charging.

{
  "success": true,
  "message": "Case payment created successfully",
  "data": {
    "result": {
      "paymentId": "9d2461f0-54b8-43dd-9507-e3143d4a50a1",
      "status": "UNPAID",
      "amount": 100,
      "description": "Refill for medication",
      "createdAt": "2026-06-30T12:00:00.000Z"
    }
  }
}

▶400Validation ErrorInvalid or missing request parameters.

{
  "status": 400,
  "success": false,
  "message": "Invalid request",
  "error": "Amount must be a positive number",
  "code": "VALIDATION_ERROR"
}

▶401UnauthorizedAPI key does not belong to the case's organization.

{
  "status": 401,
  "success": false,
  "message": "Permission Denied",
  "error": "Permission denied",
  "code": "PERMISSION_DENIED_ERROR"
}

▶400Payment FailedThe off-session charge was declined or failed (only when capture: true).

{
  "status": 400,
  "success": false,
  "message": "Invalid payment information",
  "error": "Failed to charge off-session payment: Your card was declined.",
  "code": "PAYMENT_ERROR"
}

Try It Out

Try itAPI Playground

▶