List Payments

GET/api/v1/users/me/payments

Lists the authenticated patient's case payments. Optionally filtered by case. Soft-deleted payments are excluded. Cursor-paginated by createdAt descending.

cv-api-key + Bearer accessToken

Productionhttps://api.care360-next.carevalidate.com/api/v1/users/me/payments

Staginghttps://api-staging.care360-next.carevalidate.com/api/v1/users/me/payments

Headers

Headers

cv-api-keystringrequired

Your unique API key for authentication.

Authorizationstringrequired

Bearer access token from /verify-otp.

Example: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...

Query Parameters

Query Parameters

caseIdstringoptional

UUID. Restrict the list to a single case owned by the patient. Verified via ensurePatientOwnsCase — if the case does not belong to the patient or to the calling org, returns 403.

Example: 550e8400-e29b-41d4-a716-446655440000

limitintegeroptional

Page size. 1–100. Defaults to 20.

Example: 20

afterstringoptional

Cursor — the last id from the previous page. The server skips this row and returns the next page.

Example: 550e8400-e29b-41d4-a716-446655440000

Behavior

1. If caseId is provided, ensurePatientOwnsCase confirms the case exists, the submitterId === userId, and the organizationId matches the calling org. Otherwise → 403 VALIDATION_ERROR "You do not have access to this case".
2. If caseId is omitted, the server resolves the patient's own case ids in this org.
3. The DB query returns CasePayment rows scoped to those case ids with isDeleted = false, ordered by createdAt descending. The associated CasePaymentFees row, if any, is embedded under fees (otherwise fees is null).
4. The server takes limit + 1 rows to detect end-of-results, drops the extra, and emits its id as nextCursor. When no more rows exist, nextCursor is null.

If the patient has no cases (or no payments), data.payments is [] and data.nextCursor is null.

Response Shape

See Payments Overview › Payment for the per-row field list. The response is:

{ "status": 200, "success": true, "data": { "payments": [ "..." ], "nextCursor": "<id> | null" } }

Example Request

cURL — all

curl -X GET '<BASE_URL>/api/v1/users/me/payments' \
-H 'cv-api-key: <redacted>' \
-H 'Authorization: Bearer <accessToken>'

cURL — paginated

curl -X GET '<BASE_URL>/api/v1/users/me/payments?caseId=<CASE_ID>&limit=20&after=<LAST_ID>' \
-H 'cv-api-key: <redacted>' \
-H 'Authorization: Bearer <accessToken>'

JavaScript

const url = new URL('<BASE_URL>/api/v1/users/me/payments');
url.searchParams.set('caseId', '<CASE_ID>');
url.searchParams.set('limit', '20');

const response = await fetch(url, {
method: 'GET',
headers: {
  'cv-api-key': '<redacted>',
  'Authorization': 'Bearer <accessToken>',
},
});
const data = await response.json();
console.log(data);

Python

import requests

response = requests.get(
  '<BASE_URL>/api/v1/users/me/payments',
  headers={
      'cv-api-key': '<redacted>',
      'Authorization': 'Bearer <accessToken>',
  },
  params={'caseId': '<CASE_ID>', 'limit': 20},
)
print(response.json())

Responses

▶200SuccessReturns the patient's payments matching the filters.

{
  "status": 200,
  "success": true,
  "data": {
    "payments": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "description": "Initial consultation",
        "amount": 150,
        "discountedAmount": 120,
        "status": "PAID",
        "paymentDate": "2026-04-15T12:34:56.000Z",
        "dueDate": "2026-04-10T00:00:00.000Z",
        "caseId": "550e8400-e29b-41d4-a716-446655440111",
        "createdAt": "2026-04-15T12:30:00.000Z",
        "fees": {
          "consultFee": 100,
          "convenienceFee": 5,
          "paymentProcessingFee": 4.5,
          "pharmacyFee": 0,
          "shippingFee": 10.5
        }
      }
    ],
    "nextCursor": "550e8400-e29b-41d4-a716-446655440000"
  }
}

▶400Validation errorcv-api-key missing, caseId / after not a UUID, or limit out of range.

{
  "status": 400,
  "success": false,
  "error": "Validation failed",
  "code": "VALIDATION_ERROR"
}

▶401Authentication failureAuth-middleware rejection (any cause is collapsed into this generic response).

{
  "status": 401,
  "success": false,
  "error": "Invalid or expired token",
  "code": "VALIDATION_ERROR"
}

▶403Case not ownedcaseId does not belong to the patient or to the calling org.

{
  "status": 403,
  "success": false,
  "error": "You do not have access to this case",
  "code": "VALIDATION_ERROR"
}

Try It Out

Try itAPI Playground

▶