Record an insurer's payment
- Sandbox: available
- On your own host? Choose https://{host} in the playground.
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_claimsupdateand let you read each claim's patient, else 403PATIENT_BILLING_NOT_ALLOWEDor 404CLAIM_NOT_FOUND. - Every claim must be active, of the clinic
clinicIdnames, and to the same insurer, which is the payer. The allocations must add up toamount, in its currency. Else 422PAYMENT_ALLOCATION_INVALID. - Amounts are more than zero. Every claim's total must be in the payment's currency.
identifieris 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 withLocation: /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 }'bearerAuthorizationBearer <JWT>application/json- body
identifier*The insurer's id for the payment, from the remittance: the same identifier again is the same payment.
clinicId*stringThe clinic paid.
^[A-Za-z0-9\-.]{1,64}$paidOn*stringamount*What the insurer paid in all.
allocations*array<>How the payment splits across claims; the amounts add up to amount.
1 <= items <= 100disposition?stringThe insurer's note on the remittance.
1 <= length <= 200nullA payment with this identifier was recorded before.
application/json- response
id*stringversion*stringSend it as If-Match: W/"<version>" to change only this version.
identifier*clinicId*stringinsurer*paidOn*stringamount*disposition*stringallocations*array<>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" } } ]}'{ "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" } } ]}Get an eligibility check GET
Reads one eligibility check and its answer. **Scope:** the caller's project, with `PATIENT_BILLING_ENABLED` on. ## Behaviour - Your access policy must grant `patient_billing_claims` `read`, else **403** `PATIENT_BILLING_NOT_ALLOWED`. A check whose patient you cannot read answers **404** `ELIGIBILITY_CHECK_NOT_FOUND`. ## Example ```bash curl 'https://api.sandbox.ovok.com/v1/patient-billing/eligibility-checks/<checkId>' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' ```
Get a payment GET
Reads one insurer's payment and how it splits across claims. **Scope:** the caller's project, with `PATIENT_BILLING_ENABLED` on. ## Behaviour - Your access policy must grant `patient_billing_claims` `read` and let you read every patient whose claim it pays, else **404** `PAYMENT_NOT_FOUND`. ## Example ```bash curl 'https://api.sandbox.ovok.com/v1/patient-billing/payments/<paymentId>' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' ```