API Reference

Payments

🚧

This endpoint is in beta and as such all content below is subject to change.

🚧

Supported Integrations

For now, payments are only supported for Open Dental and Dentrix.

Payments represents a patient or their insurance plan paying for a completed service or good(s). Payments are a "credit" meaning they subtract from the patient balance, reducing the amount the patient owes the practice.

It is important to note that this endpoint reflect payments that have been input into the health record system regardless of whether the practice actually received a payment in their bank account. Practices may input payments before or after the "actual" payment is received and processed.

Reading Payments

Determining Responsible Party

You can determine whether a patient or their insurance was responsible for a payment by referring to the insurance_plan_id and claim_id. Please note that these values are only available via view payment (singular).

A null value in insurance_plan_id and claim_id indicates that the patient paid out of pocket while a non null value indicates that the patient's insurance provided the payment. Passing the insurance_plan_id in a call to view insurance plan (singular) will return the name of the insurance and the employer, as well as other optional values such as patient_coverages and subscribers.


Creating Payments

❗️

Asynchronous payment creation

Please note that creating a payment transaction via the NexHealth API is asynchronous, therefore it is strongly recommended that you also subscribe to the payment transaction insertion webhook which will fires upon complete or failed response from an integration when inserting a patient payment into an EHR.

Depending on the integration, the creation of payment transaction which includes payment_splits may result in multiple payment records in the target EHR. In order to associate the payment transaction with the resulting payment(s), please match on transaction_id.

Transaction ID

The creation of one payment transaction may result in multiple payment records in the target practice management system. Therefore a NexHealth payment transaction may have a one to many relationship with the corresponding patient payment ledger line items in the target database. For this reason, NexHealth requires that API users manage transaction IDs.

The payment_transactions.transaction_id entered will be stored as the resulting payments.transaction_id and may be used to match payments with the payment transaction that generated them.

Transaction ids are a customer generated id and must be unique. Please construct your id by combining a prefix identifying your company name. For example, three consecutive payment transactions created by NexHealth may be as follows: "NH:201", "NH:202", "NH:203".

Type name

This field allows for the customization of payment types on payments created via the NexHealth API. Payment types identify the method used to make a payment (e.g., cash, credit card, check). Please note that payment type names may be unique and that when creating a payment transaction, the type name field must exactly match. Attempts to create a payment transaction with a type name that does not match an existing payment type name in the target practice management system will result in an error. To understand which payment types are available, please first make a call to view payment types. More information can be found on the payment types documentation page.

Provider and charge splits

NexHealth offers the ability to split a charge between different providers or charges. Please note that these are value splits and therefore the sum of the splits must equal the total amount of the payment transaction. Provider and charge splits with a sum not equal to the total amount of the payment transaction will result in an error.

NB: You may only split a payment transaction among entities of the same kind. In other words, when creating a payment transaction, you may indicate either a provider split or a charge split. Payment transactions indicating both a provider and charge split will result in an error.

  • Provider split: A provider represent an employee who can be booked for an appointment at a given practice. Provider splits may be used if the office receives a single payment and wants to allocate a portion of that payment to one or more providers.
  • Charge split: A charge in NexHealth represents a patient or their insurance plan being charged money for a service provided. In Sikka this is called a “completed procedure”. A charge split may be used if the office wishes to indicate that one payment covers 2 charges/completed procedures.

🚧

It is not possible to associate a payment in Dentrix with a charge, so the synchronizer will instead find and use the provider associated to that charge. In other words, if you create a payment transaction for a Dentrix office via the NexHealth API and pass a charge split, the resulting payment created in Dentrix will have a provider association instead of a charge.

Example call

In the example below, this payment transaction has a total amount of $150 USD which is split $100 to the provider with id 001 and $50 to the provider with id 002.

{
  "payment_transaction": {
    "currency": "USD",
    "provider_splits": {
      "001": "100",
      "002": "50"
    },
    "patient_id": 1234,
    "amount": 150,
    "type_name": "NexHealth Credit Card Payment",
    "transaction_id": "NH:201",
    "paid_at": "2024-11-30"
  }
}