Payments & Subscriptions

Base URL: https://api.welkinhealth.com/{tenantName}/{instanceName}/patients/{patientId}/payments

The Payments API provides read access to patient payment records and billing information integrated with Welkin.

---

Get All Payments for Patient

GET /patients/{patientId}/payments

Returns a paginated list of payment records for a patient.

Path Parameters

Parameter	Type	Required	Description
patientId	string	Yes	ID of the patient

Query Parameters

Parameter	Type	Required	Description
status	string	No	Filter by status: PENDING, PAID, FAILED, REFUNDED
startDate	string (ISO 8601)	No	Filter from payment date
endDate	string (ISO 8601)	No	Filter to payment date
page	integer	No	Page number (default: 0)
size	integer	No	Page size (default: 20)

Example Request

curl -X GET "https://api.welkinhealth.com/acme/live/patients/pt_7f3a9b2c-1d4e-4f8a-b5c6-d7e8f9a0b1c2/payments?status=PAID" \
  -H "Authorization: Bearer {access_token}"

Example Response

{
  "content": [
    {
      "id": "pay_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "patientId": "pt_7f3a9b2c-1d4e-4f8a-b5c6-d7e8f9a0b1c2",
      "encounterId": "enc_c3d4e5f6-a7b8-9012-cdef-123456789012",
      "amount": 150.00,
      "currency": "USD",
      "status": "PAID",
      "method": "CREDIT_CARD",
      "paidAt": "2026-03-15T12:00:00Z",
      "invoiceId": "inv_d4e5f6a7-b8c9-0123-defa-234567890123",
      "notes": "Co-pay collected at visit"
    }
  ],
  "totalElements": 1,
  "totalPages": 1,
  "page": 0,
  "size": 20
}

---

Get Payment by ID

GET /patients/{patientId}/payments/{paymentId}

Returns a single payment record.

Path Parameters

Parameter	Type	Required	Description
patientId	string	Yes	ID of the patient
paymentId	string	Yes	ID of the payment

Example Request

curl -X GET "https://api.welkinhealth.com/acme/live/patients/pt_7f3a9b2c-1d4e-4f8a-b5c6-d7e8f9a0b1c2/payments/pay_a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer {access_token}"

Example Response

{
  "id": "pay_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "patientId": "pt_7f3a9b2c-1d4e-4f8a-b5c6-d7e8f9a0b1c2",
  "encounterId": "enc_c3d4e5f6-a7b8-9012-cdef-123456789012",
  "amount": 150.00,
  "currency": "USD",
  "status": "PAID",
  "method": "CREDIT_CARD",
  "paidAt": "2026-03-15T12:00:00Z",
  "invoiceId": "inv_d4e5f6a7-b8c9-0123-defa-234567890123",
  "notes": "Co-pay collected at visit"
}

---

Payment Object

Field	Type	Description
id	string	Payment UUID
patientId	string	Associated patient
encounterId	string	Associated encounter (optional)
amount	number	Payment amount
currency	string	Currency code (e.g., USD)
status	string	PENDING, PAID, FAILED, or REFUNDED
method	string	Payment method
paidAt	datetime	Payment timestamp
invoiceId	string	Associated invoice (optional)

Note: Payment creation and processing are handled through Welkin's billing integration. Contact your Welkin implementation team for billing integration configuration.