Payments

GET /payments and GET /payments/{id} require an explicit live practice-key read_payments grant. Patient and invoice grants do not imply it; existing keys are not upgraded. This is a read of native payments records, not provider charge discovery, financial reconciliation or a facility for taking/refunding payments.

The payment, joined invoice and joined patient must belong to the practice, and the payment's patient must equal the invoice's patient. Invoice references must be in the issued-invoice lifecycle, excluding draft/null/unknown states. An invoice ID in this response grants no access to invoice amounts or payment URLs.

List accepts patient_id, invoice_id, payment_status, payment_method, payment_date_gte, payment_date_lte, limit (default 20, maximum 100), and offset (maximum 100000). Date bounds are UTC instants in YYYY-MM-DDTHH:mm:ssZ form. Unknown, empty, repeated or invalid parameters return 422. Foreign/unavailable patient or invoice filters, including mismatched patient and invoice combinations, return 404 even for empty lists. Get accepts a UUID and no query parameters. Sort is created_at DESC, id DESC, with one lookahead for has_more and next_offset; concurrent changes can shift offset pages.

Native statuses are succeeded, completed, paid, refunded, partially_refunded and held_as_credit. Methods covered are card, stripe, saved_card, cash, cheque, bank_transfer, terminal, card_terminal, other, refund and balance_credit. Other/unknown states or methods are not included in this initial contract, so this is not an exhaustive ledger export. Status and method are preserved without inferring provider reconciliation, refundability or final invoice settlement.

Response fields are payment UUID, patient/invoice UUIDs, amount_cents, currency, native method/status, payment date and creation/update dates. Amounts must be safe integer minor units. Negative refund or credit entries and zero values remain signed values; a held balance credit is not relabelled as a refund. Currency is the recorded three-letter code with its original case, never an assumed default. Missing/malformed currency fails closed. No balance or net-paid total is computed.

Provider IDs, external payment details, notes, actors, bank/card information and URLs are not exposed. Example: GET /payments?invoice_id=16297000-0000-4000-8000-000000000005&payment_status=completed. Responses use {data, meta} with pagination metadata for list and request ID for both operations. Successful reads use Cache-Control: no-store. First-party request logs retain key/practice attribution; resource analytics use the fixed /api-v1/payments label without payment IDs or query filters.

No MCP/FHIR activation or financial mutation is added. Hosted CI, final security review and deployed PostgREST/staging acceptance remain pending until reviewed.

curl -X GET "https://example.com/payments"

{  "data": [    {      "id": "string",      "patient_id": "string",      "invoice_id": "string",      "amount_cents": 0,      "currency": "string",      "payment_method": "card",      "payment_status": "succeeded",      "payment_date": "string",      "created_at": "string",      "updated_at": "string"    }  ],  "meta": {    "limit": 20,    "next_offset": 1,    "has_more": true,    "request_id": "req_abc123"  }}

curl -X GET "https://example.com/payments/497f6eca-6276-4993-bfeb-53cbbbba6f08"

{  "data": {    "id": "string",    "patient_id": "string",    "invoice_id": "string",    "amount_cents": 0,    "currency": "string",    "payment_method": "card",    "payment_status": "succeeded",    "payment_date": "string",    "created_at": "string",    "updated_at": "string"  },  "meta": {    "request_id": "req_abc123"  }}