Get started with payments

🚧

Get access

To access financial endpoints, please email [email protected].

Introduction

This guide walks you through how to use NexHealth's Ledger API to collect patient payments. It explains how to:

1. Find the amount owed
2. Collect information to create an itemized invoice
3. Insert payment transactions in the patient’s EHR ledger.

Step 1: Find the amount owed

Overview

The NexHealth API does not provide a direct method to retrieve an individual patient’s balance. However, you can:

• Retrieve the balance owed by a guarantor (fiscally responsible party).
• Calculate a patient’s balance by summing charges, payments, and adjustments.

Retrieve guarantor balance

Please note that a guarantor may be associated with multiple patients. Guarantor balance will reflect the total balance for all those patients.

1. Identify the guarantor

• Use the view patient endpoint to find the guarantor_id associated with the patient. If the patient is their own guarantor, the patient_id and guarantor_id will be the same.
• Optionally, include the guarantor parameter to retrieve the guarantor’s contact details.

2. View balance

• Use the view balance endpoint and pass in the guarantor_id.
• The guarantor_portion field on the response represents the amount the practices believes a guarantor owes (the delta between guarantor_portion and total_balance is either covered by insurance or written off)

Calculate Patient Balance

1. Sum charges: Use the view charges endpoint to retrieve the list of charges for the patient.
   1. Calculate the patient amount:

patient_amount = charge.fee - charge.payment_estimate_total  charge.write_off_estimate_total

patient_amount = charge.fee - charge.write_off_total

2. Sum payments:
   Use the view payments endpoint and sum thepayment_amount.amountvalues.
3. Sum adjustments:
   Use the view adjustments endpoint and sum the adjustment_amount.amount values.
4. Validate calculations:
   Sum charges, payments, and adjustments to calculate the total balance. Compare this value to the guarantor_portion from the accounts receivable record. Discrepancies may indicate missing ledger items or data inconsistencies.

Step 2: Retrieve charge details for itemized invoices

To create itemized invoices or group charges by attributes such as patient, provider, or date:

1. Fetch charge details:
   1. For each charge from Step 1, use the view_charge action to retrieve additional details such as:
   2. Patient name
   3. Provider
   4. Procedure information
   5. Claim details.
2. Get detailed procedure information:
   1. If a charge is associated with a completed procedure, you can view the procedure by adding the query parameter include\[]=procedures to the /charges query.
   2. However, not all EHRs enforce or even allow this mapping. For more details per integration, please see the Supported Health Record Systems section on the charges documentation.

Step 3: Insert payments into the ledger

Once a payment is collected, it must be recorded in the practice’s ledger.

Steps to record payments

1. Retrieve payment types
   1. Use the view payment types action to fetch available payment types in the target EHR.
      Select the appropriate payment_type_id for your transaction.
2. Create a payment transaction
   1. Use the create payment transaction endpoint to record the payment. Include all available details in the payment_transaction object.
   2. To associate payments with providers or charges, use the provider_splits and charge_splits fields. See the corresponding section in this document to learn how.
   3. One payment transaction may result in multiple payment records in the target health record 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 allows API users to pass in a transaction_id.
   4. 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.
   5. If you want to subscribe to updates, use the create webhook subscription endpoint. Subscribing to the payment_transaction_insertion event will ensure you are notified when payment records are created in the target health record system. Please note that payment creation is asynchronous and can fail.
      
      

/