Create Patient Debt or Payment

Creates a standalone debt, an income collection, or a refund for a patient. The payload rules depend on payment_method_id and type.

POST

/:tenantId/patients/:patientId/payments

Add debt

Use payment method 0, include user_id, and omit type, items, and settlement.

{
  "user_id": 11,
  "payment_method_id": 0,
  "amount": 1000,
  "currency": "TRY",
  "fulfilled_date": "2026-01-15 10:00",
  "title": "Treatment debt",
  "note": "Standalone patient debt",
  "exchange_rate_type": 2,
  "exchange_rate": 1
}

Add collection

Use a real payment method and set type to income. Optional items distribute the collection to active doctors/admins; their total cannot exceed the payment amount.

{
  "payment_method_id": 2,
  "type": "income",
  "amount": 400,
  "currency": "TRY",
  "fulfilled_date": "2026-01-15 10:15",
  "title": "Credit card collection",
  "note": "Partial collection",
  "items": [
    {
      "user_id": 11,
      "amount": 400
    }
  ],
  "exchange_rate_type": 2,
  "exchange_rate": 1
}

Field	Type	Required	Description
payment_method_id	integer	yes	0 debt, 1 cash, 2 credit card, 3 wire transfer, 4 mail order, 5 check.
user_id	integer	debt only	Required for debt; prohibited for distributed payments and cross-currency settlements.
type	string	payment only	income or refund. Prohibited for debt and settlement payloads.
amount	number	yes	Amount greater than 0.
currency	string	yes	Record currency.
fulfilled_date	datetime	no	Date in YYYY-MM-DD HH:mm format.
appointment_id	integer	no	Appointment belonging to the same patient.
title	string	no	Maximum 32 characters.
note	string	no	Financial record note.
items	array	no	Optional collection distribution. Each entry requires an active user_id and an amount greater than 0.
exchange_rate_type	integer	no	1 fixed, 2 dynamic.
exchange_rate	number	no	Exchange rate, minimum 0.0001.

Response

HTTP 201 Created

{
  "data": {
    "id": 45002,
    "patient_id": 188413,
    "appointment_id": null,
    "user_id": null,
    "title": "Credit card collection",
    "type": "income",
    "payment_method": {
      "id": 2,
      "name": "credit_card"
    },
    "amount": "400.00",
    "currency": "TRY",
    "exchange_rate_type": 2,
    "exchange_rate": 1,
    "base_amount": "400.00",
    "base_currency": "TRY",
    "fulfilled_date": "2026-01-15T10:15:00.000000Z",
    "record_type": null,
    "financeable_id": null,
    "financeable_active": false,
    "financeable_summary": null,
    "split_group": null,
    "settlement": null,
    "note": "Partial collection",
    "financial_amounts_masked": false
  }
}

HTTP 422 Unprocessable Content is returned when the selected payload mode conflicts with payment_method_id, distribution totals are invalid, or the appointment does not belong to the patient.