Payments

Overview

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. As such, a payment of $125 is represented as -125.00 because payments are credits which by convention are negative values in the ledger.

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.

Positive valued payments are debit adjustments, otherwise called refunds. For more guidance on positive valued payments, see the "Supported Health Record Systems" section below.

Use Cases

Creating New Patient Payments as Ledger Line Items

The primary use case for the payments endpoint is to allow users to create new payments in the target EHR. The creation of one payment transaction may result in multiple payment records in the target database. Therefore a NexHealth payment transaction may have a one to many relationship with the corresponding patient payment ledger line items in the EHR. For this reason, NexHealth requires that API users manage transaction IDs (see below for more information).

Creating Insurance Payments

Insurance payments are payment records which have a non null claim_id and insurance_plan_id. While it is possible to create a payment regardless of it's source, the create payment transactions action does not currently support these fields and therefore the NexHealth API doesn't fully support the automated creation of insurance payments. Any additional contextual information which cannot be passed in the payment_transaction object body must be entered as a note. Any updates to the payment after it's creation in the EHR must be completed manually from within the EHR UI directly.

Patient Balance

The NexHealth API does not provide individual patient balance; however, it can be calculated by adding together charges, payments and adjustments associated to a particular patient.

Determining Responsible Party

You can determine whether a patient or their insurance was responsible for a payment by referring to the claim_id. A null value in claim_id indicates that the patient paid out of pocket while a non null value indicates that the patient's insurance provided the payment.

Requesting Additional Associated Entities

For collection queries (/payments), only the id of the associated entities are returned in the response. However, the single :id query can include additional related record details. Please refer to the include[] query parameter on the view payment page for a current list of available options. Also note that payment to charge relationships are not always available and therefore may return null values. For more guidance on payment to charge relationship mappings, see the "Supported Health Record Systems" section below.

Creating Payments

❗️

Asynchronous payment creation - the importance of webhooks

Please note that creating a payment transaction via the NexHealth API is asynchronous and therefore it is necessary to subscribe to the payment transaction insertion webhook which fires upon complete or failed response from an integration when inserting payments 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 offices may manually create their own payment types and therefore, they may vary from office to office. When creating a payment transaction, the type name field must exactly match the payment type name from the specific database, including capitalization. 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.

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.
  • In the example below, this payment transaction has a total amount of $150 which is split as follows: $100 to the provider with id 001 and $50 to the provider with id 002.

    "provider_splits": {
      "001": "-100",
      "002": "-50"
    },
    

• Charge split: A charge in NexHealth represents a patient or their insurance plan being charged money for a service provided. Charges may also be referred to as “completed procedures”. A charge split may be used if the office wishes to indicate that one payment covers 2 charges/completed procedures. For more guidance on payment to charge relationship mappings, see the "Supported Health Record Systems" section below.
  • In the example below, this payment transaction has a total amount of $500 which is split as follows: $125 to the charge with id 113 and $375 to the charge with id 114.

    "charge_splits": {
      "113": "-125",
      "114": "-375"
    },
    

Supported Health Record Systems