Patient billing

Record an insurer's payment

  • Sandbox: available
  • On your own host? Choose https://{host} in the playground.
POST
/v1/patient-billing/payments

Records an insurer's payment to a clinic from its remittance: a FHIR PaymentReconciliation that splits it across the claims it pays, and a PaymentNotice per claim.

Scope: the caller's project, with PATIENT_BILLING_ENABLED on.

Behaviour

  • Your access policy must grant patient_billing_claims update and let you read each claim's patient, else 403 PATIENT_BILLING_NOT_ALLOWED or 404 CLAIM_NOT_FOUND.
  • Every claim must be active, of the clinic clinicId names, and to the same insurer, which is the payer. The allocations must add up to amount, in its currency. Else 422 PAYMENT_ALLOCATION_INVALID.
  • Amounts are more than zero. Every claim's total must be in the payment's currency.
  • identifier is the insurer's id for the payment: the same identifier at the same clinic again answers the payment already recorded, with 200. A new one answers 201 with Location: /v1/patient-billing/payments/<id>.
  • It is recorded holding the locks of the patients whose claims it pays, so none is withdrawn meanwhile; another change to one of them running at the same time answers 409; send it again.

Example

curl -X POST 'https://api.sandbox.ovok.com/v1/patient-billing/payments' \  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \  -H 'Content-Type: application/json' \  -d '{ "identifier": { "system": "https://example.com/remittances", "value": "R-2026-11-0042" }, "clinicId": "<clinicId>", "paidOn": "2026-11-30", "amount": { "value": 31.62, "currency": "EUR" }, "allocations": [{ "claimId": "<claimId>", "amount": { "value": 31.62, "currency": "EUR" } }], "disposition": null }'

Authorization

bearer
headerAuthorizationBearer <JWT>

Request Body

application/json
  1. body
identifier*

The insurer's id for the payment, from the remittance: the same identifier again is the same payment.

clinicId*string

The clinic paid.

Match^[A-Za-z0-9\-.]{1,64}$
paidOn*string
amount*

What the insurer paid in all.

allocations*array<>

How the payment splits across claims; the amounts add up to amount.

Items1 <= items <= 100
disposition?string

The insurer's note on the remittance.

Length1 <= length <= 200
Defaultnull

Response Body

A payment with this identifier was recorded before.

application/json
  1. response
id*string
version*string

Send it as If-Match: W/"<version>" to change only this version.

identifier*
clinicId*string
insurer*
paidOn*string
amount*
disposition*string
allocations*array<>
Example Request
curl -X POST 'https://api.sandbox.ovok.com/v1/patient-billing/payments' \  -H 'Content-Type: application/json' \  -d '{  "identifier": {    "system": "http://example.com",    "value": "string"  },  "clinicId": "string",  "paidOn": "string",  "amount": {    "value": 0,    "currency": "string"  },  "allocations": [    {      "claimId": "string",      "amount": {        "value": 0,        "currency": "string"      }    }  ]}'
Example Response
{  "id": "string",  "version": "string",  "identifier": {    "system": "string",    "value": "string"  },  "clinicId": "string",  "insurer": {    "id": "string",    "ik": "string",    "name": "string"  },  "paidOn": "string",  "amount": {    "value": 0,    "currency": "string"  },  "disposition": "string",  "allocations": [    {      "claimId": "string",      "amount": {        "value": 0,        "currency": "string"      }    }  ]}