💡 Payments are in V2. In Swagger, choose V2 Api in the Select a definition dropdown. POST /v1/patients/{patientId}/payments is deprecated; use POST /v2/payments instead.
How Payments Work
A payment is recorded in two steps:
Create the payment, the money received: amount, method, date, and who paid (an insurance payer or a patient).
Apply it to invoices by adding payment invoices to the payment, each with the amount paid, adjustments, and optionally service-line detail.
Payment status moves from New to Applied (or Unapplied), and then to Completed. Any amount not yet applied shows as UnappliedAmount.
Before You Start: Lookups
What you need | Endpoint | Example |
Billing provider |
|
|
Payer (insurance payments) |
|
|
Invoices to apply to |
|
|
Adjustment group codes |
|
|
Adjustment reason codes |
|
|
Remark codes |
|
|
Provider-level adjustment codes |
|
|
Step 1: Create a Payment
POST /v2/payments
Fields
Field | Required | Notes |
| ✅ |
|
| When | From |
| When | Numeric patient ID |
| ✅ | Decimal, e.g. |
| ✅ |
|
| ✅ |
|
|
| From |
|
| Check, EFT trace, or transaction number |
|
| Free text |
|
| PLB adjustments: |
|
|
|
|
|
|
Example: insurance check payment
POST /v2/payments
{
"SourceType": "Insurance",
"PayerId": "31336912e90ee028e420ad823d50a3763b4bc5ef",
"BillingProviderId": "BP28538d00acea414bbc940e0fda497f92",
"PaymentAmount": 450.00,
"Method": "Check",
"RemittanceDate": "2026-11-10",
"ReferenceNumber": "49879879879"
}
Response: 201 Created
{ "Id": "PTed2f0f00ef4b8ce90c1455b45d70b159" }
Step 2: Apply the Payment to Invoices
POST /v2/payments/{paymentId}/invoices
Add one or more payment invoices to the payment.
💡 Link the invoice to save work. If you include InvoiceId, any optional fields you leave out are filled in from the invoice.
Payment Invoice Fields
Field | Required | Notes |
| ✅ | Amount paid on this invoice |
|
| The NikoHealth invoice being paid |
|
| Amount billed |
|
|
|
|
| The payer's claim number |
|
| Claim-level adjustments (see below) |
|
| Remark codes, e.g. |
|
| Service-line detail (see below) |
|
| Patient details ( |
Adjustments
Field | Required | Notes |
| ✅ |
|
| ✅ | Adjustment reason code, e.g. |
| ✅ | Decimal |
Service Lines (PaymentServices)
Field | Required | Notes |
| ✅ | HCPCS code paid |
| ✅ | Units paid |
| ✅ | Line charge |
| ✅ | Line payment |
|
| Allowed amount |
|
| Line-level adjustments (same shape as above) |
|
| Line-level remark codes |
|
| What was billed: |
|
| The invoice service line being paid |
|
| The payer's line control number |
Example: apply to one invoice with a contractual adjustment
POST /v2/payments/PTed2f0f00ef4b8ce90c1455b45d70b159/invoices
{
"Invoices": [
{
"InvoiceId": "IN9fa1d300ff4b39ab984449c5267b72f1",
"PayerLevel": "Primary",
"ClaimControlNumber": "2026310000123",
"ChargeAmount": 600.00,
"PaymentAmount": 450.00,
"Adjustments": [
{ "Group": "CO", "Reason": "45", "Amount": 150.00 }
]
}
]
}
Response: Returns the created payment invoice ID(s).
View Payments
Search payments
GET /v2/payments
Filter | Notes |
|
|
| Payer ID or patient ID |
| Payments applied to an invoice |
|
|
|
|
| Check or EFT number |
| Remittance date range |
| Also |
| Date-time ranges |
| Include deleted payments |
| Paging |
{
"Items": [
{
"Id": "PTed2f0f00ef4b8ce90c1455b45d70b159",
"Status": { "Id": "Applied", "Name": "Applied" },
"Method": { "Id": "Check", "Name": "Check" },
"SourceType": { "Id": "Insurance", "Name": "Insurance" },
"SourceId": "31336912e90ee028e420ad823d50a3763b4bc5ef",
"PaymentAmount": 450,
"TotalAmount": 450,
"UnappliedAmount": 0,
"RemittanceDate": "2026-11-10T00:00:00",
"ReferenceNumber": "49879879879",
"BillingProvider": { "Id": "BP28538d00acea414bbc940e0fda497f92", "Npi": "1234567890", "Name": "Example Medical Supply" },
"Locked": false,
"Archived": false
}
]
}
Get one payment: GET /v2/payments/{id}
List a payment's invoices: GET /v2/payments/{paymentId}/invoices, with filters invoiceIds, paymentInvoiceIds, remittedHcpcsCodes, claimControlNumbers, dateOfService.from/.to, and status (Applied or Failed).
Update and Delete
Endpoint | Notes |
| ⚠️ Send the entire payment. Fields you leave out may be removed. |
| Optional fields you leave out keep their existing values. |
| The payment is archived, not permanently deleted, and is no longer visible in the UI. |
| Removes a payment invoice from the payment. |
Get Notified of Changes
Subscribe to payment.created, payment.updated, payment.deleted, and patient.payment.created.
See Webhooks API.
Common Errors
Code | Meaning |
| Invalid request, e.g. a missing |
| Token missing, expired, or invalid |
| You don't have permission to access this resource |
| Payment, payment invoice, or invoice not found |
| Too many requests |
