Payments

Record payments you’ve taken through your own system against a patient’s Vodett invoice.

Warning: Recording a payment is final. There is no API endpoint to undo, edit, or delete a recorded payment, and a posted payment cannot be removed. Make sure the amount and method are correct before you post it.

GET /invoices

List the clinic’s invoices with their outstanding balance. Requires the billing module.

Parameters (query):

patient_id (optional — filter to one patient)
unpaid (bool, optional — only invoices with a balance)

Request

curl "https://api.vodett.ai/api/public/v1/invoices?unpaid=true" \
  -H "Authorization: Bearer vodett_sk_live_your_key_here"

Response

[
  { "id": "…uuid…", "invoice_number": "INV-000123", "patient_id": "…uuid…", "status": "issued", "currency": "EUR", "total": 100.0, "amount_paid": 0.0, "balance": 100.0, "issued_at": "2026-08-20T09:00:00Z" }
]

Use the invoice id and balance to record a payment below.

POST /invoices/{invoice_id}/payments

Records a payment against an invoice. Requires the payments module.

Parameters (JSON body):

amount (number, required — greater than 0, up to the balance)
method (string, required — one of cash, card, bank, other)
note (string, optional — recommended for method: other)

Optional header Idempotency-Key: send a unique key to make retries safe — a repeat with the same key returns the original payment instead of charging twice.

Request

curl -X POST https://api.vodett.ai/api/public/v1/invoices/INVOICE_ID/payments \
  -H "Authorization: Bearer vodett_sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c1d2e33-unique-per-payment" \
  -d '{"amount":40.00,"method":"card"}'

Response

{ "payment_id": "…uuid…", "invoice_id": "…uuid…", "patient_id": "…uuid…", "amount": 40.0, "method": "card", "currency": "EUR", "created_at": "2026-08-25T12:34:56Z", "invoice_status": "partially_paid", "invoice_total": 100.0, "invoice_amount_paid": 40.0, "invoice_balance": 60.0 }

Partial payments are supported — pay any amount up to the balance; the invoice becomes paid when the balance reaches zero, and the patient is notified. A payment above the remaining balance is rejected.

GET /payment-methods

Lists the valid payment methods.

Response

[
  { "key": "cash", "requires_note": false },
  { "key": "card", "requires_note": false },
  { "key": "bank", "requires_note": false },
  { "key": "other", "requires_note": true }
]

requires_note is a hint — include a note when using other to describe the method.