Skip to main content

Payments via API (V2)

Record insurance and patient payments, and apply them to invoices, including service-line amounts and adjustments.

💡 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:

  1. Create the payment, the money received: amount, method, date, and who paid (an insurance payer or a patient).

  2. 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

GET /v1/billing-providers

BP28538d00acea414bbc940e0fda497f92

Payer (insurance payments)

GET /v1/payers/dictionary

31336912e90ee028e420ad823d50a3763b4bc5ef

Invoices to apply to

GET /v1/invoices or GET /v2/invoices

IN9fa1d300ff4b39ab984449c5267b72f1

Adjustment group codes

GET /v1/payer-adjustments/groups

CO, PR, OA, PI

Adjustment reason codes

GET /v1/payer-adjustments/reasons

1 (Deductible Amount), 2 (Coinsurance Amount)

Remark codes

GET /v1/payer-remark-codes

Provider-level adjustment codes

GET /v1/provider-level-adjustments


Step 1: Create a Payment

POST /v2/payments

Fields

Field

Required

Notes

SourceType

✅

Insurance or Patient

PayerId

When SourceType is Insurance

From GET /v1/payers/dictionary

PatientId

When SourceType is Patient

Numeric patient ID

PaymentAmount

✅

Decimal, e.g. 450.00

Method

✅

Check, Eft, CreditCard, Cash, or Other

RemittanceDate

✅

YYYY-MM-DD

BillingProviderId

From GET /v1/billing-providers

ReferenceNumber

Check, EFT trace, or transaction number

Note

Free text

ProviderLevelAdjustments

PLB adjustments: AdjustmentCode, Amount, Date (required), ProviderRefId

MarkAsCompleted

true to mark the payment completed

MarkAsLegacy

true for historical payments you're importing

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

PaymentAmount

✅

Amount paid on this invoice

InvoiceId

The NikoHealth invoice being paid

ChargeAmount

Amount billed

PayerLevel

Primary, Secondary, Tertiary, or Other

ClaimControlNumber

The payer's claim number

Adjustments

Claim-level adjustments (see below)

RemarkCodes

Remark codes, e.g. ["N130"]

PaymentServices

Service-line detail (see below)

Patient

Patient details (Id, FirstName, LastName, DateOfBirth), if not linking an invoice

Adjustments

Field

Required

Notes

Group

✅

CO (Contractual Obligation), PR (Patient Responsibility), OA (Other Adjustment), or PI (Payer Initiated)

Reason

✅

Adjustment reason code, e.g. 45 or 1

Amount

✅

Decimal

Service Lines (PaymentServices)

Field

Required

Notes

Remitted.Hcpcs

✅

HCPCS code paid

Remitted.Quantity

✅

Units paid

Remitted.ChargeAmount

✅

Line charge

Remitted.PaymentAmount

✅

Line payment

Remitted.PayerAllowableAmount

Allowed amount

Remitted.Adjustments

Line-level adjustments (same shape as above)

Remitted.RemarkCodes

Line-level remark codes

Submitted

What was billed: Hcpcs, Quantity, DateOfService (From/To), and Modifiers (Level1–Level4)

InvoiceServiceLineId

The invoice service line being paid

ServiceLineControlNumber

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

sourceType

Insurance or Patient

sourceId

Payer ID or patient ID

invoiceId

Payments applied to an invoice

paymentStatus

New, Applied, Unapplied, Failed, Completed

method

Check, Eft, CreditCard, Cash, Other

referenceNumber

Check or EFT number

remittanceDateRange.from / .to

Remittance date range

paymentAmountRange.from / .to

Also adjustmentAmountRange, totalAmountRange, unappliedAmountRange

created.from / modified.from (and .to)

Date-time ranges

includeArchived

Include deleted payments

pageIndex / pageSize

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

PUT /v2/payments/{id}

⚠️ Send the entire payment. Fields you leave out may be removed. BillingProviderId, Method, PaymentAmount, and RemittanceDate are required.

PUT /v2/payments/{paymentId}/invoices/{paymentInvoiceId}

Optional fields you leave out keep their existing values. PaymentAmount is required.

DELETE /v2/payments/{id}

The payment is archived, not permanently deleted, and is no longer visible in the UI.

DELETE /v2/payments/{paymentId}/invoices/{paymentInvoiceId}

Removes a payment invoice from the payment.


Get Notified of Changes

Subscribe to payment.created, payment.updated, payment.deleted, and patient.payment.created.


Common Errors

Code

Meaning

400

Invalid request, e.g. a missing PayerId for an insurance payment, a missing PatientId for a patient payment, or an invalid adjustment group

401

Token missing, expired, or invalid

403

You don't have permission to access this resource

404

Payment, payment invoice, or invoice not found

429

Too many requests


Related articles

Did this answer your question?