In this guide, you will create a payment through the NexHealth API, which will pay off an example outstanding patient balance inside of an active EHR (Open Dental).

If you are building a financial/ledger product, this guide will be a great place to start.

Your First Payment

By following this guide, you will get a developer portal account setup, install the NexHealth Synchronizer, and pay off a test patient’s outstanding balance in Open Dental

Step 1: Preparation

Set Up a Developer Account

If you haven’t already, you will need to get setup with a developer account. You can follow our developer portal quickstart guide to get setup if you don't have an account already. Note down your API key as it will be needed for subsequent steps.

Organization

In order to post a payment, we will have many pieces of information that we will need to gather first. In order to keep the process of gathering this information organized, we have created an example spreadsheet for you to use. There is a cell to store your API key as well.

This spreadsheet is broken up into three sections, with each section representing a step we will complete in this guide. The white cells are meant to store data you obtain throughout this guide. The orange cells are automatically generated and will not need any manual input.

To use this sheet, open the link for it mentioned above, click "File" near the top-left corner, and click "Make a copy." Once you have a copy, we can start filling it with data.

For the "API Key" value, you can enter the sandbox API key you received after creating your developer account.

For the "Subdomain" and "Location ID" values, we will need to obtain these from our Open Dental location in the developer portal. To do so:

1. Log into the developer portal at https://developers.nexhealth.com/
2. Click "Institutions" on the left and click on the name of your demo practice
3. Just under the title of the institution is the subdomain - click the subdomain to copy it and add it to the spreadsheet
4. Locate the Open Dental location you would like to use and find the location ID on the right side of the page - click the ID to copy it and add it to the spreadsheet

Step 2: Gathering Charges

Before we can make a payment in Open Dental, we want to find a balance that needs to be paid off. Fortunately for us, the Open Dental demo version comes pre-populated with test patients that have active balances on the Open Dental ledger.

Specifically what we care about for these patients is their charges. A charge is going to be a line item on the ledger that increases the patient’s balance and is associated with a completed procedure that was performed on the patient.

In the image above we have a charge for a prophylaxis (routine cleaning) procedure for this test patient John Smith of $70. In the following steps for this section, we are going to find this patient and view their ledger in Open Dental, then we are going to locate the patient through the NexHealth API and collect their patient ID, then we are going to use that to locate their charges through the NexHealth API.

Locate the Patient and Their Charges in Open Dental

We want to start by finding our target test patient “John Smith” inside of Open Dental, and identify where in the Open Dental UI we can view their ledger.

1. On the main appointments page inside of Open Dental, click the “Select Patient” button

   

2. Next click on the patient John Smith, then click "OK"

   

3. Now click the Account tab - this will take us to the page where we can see John’s ledger

   
   

   In the screenshot above, we can see the procedures associated with John

Find a Patient Through the NexHealth API

Now we want to find “John Smith” through the NexHealth API. Specifically, we are aiming to collect John’s NexHealth patient ID.

1. Go to the Payments Quickstart spreadsheet you copied earlier and, inside of section 2, open up the page associated with the patient ID column

   

   This will take us to the NexHealth documentation on our GET /patients endpoint where we will be able to call the endpoint from the documentation itself

2. Place your API key into the header field

   

3. Scroll down the page and paste in the subdomain and location_id from our spreadsheet

   

4. Enter in the name of the patient that we want to look up (John Smith) and click the “Try It!” button to make the API call

   

5. In the result, we want to identify John’s patient_id, then add it to our spreadsheet

   
   

Now that we have collected John’s patient ID, we are able to use his ID to reference him through the API. You can now close the GET /patients documentation tab.

View and Collect the Patient’s Charges Through the Nexhealth API

Now we are going to collect John’s charges through the API. These are the line items on the Open Dental ledger that we saw earlier.

1. We'll by going to the GET /charges endpoint documentation

   

2. Next, we will enter in the API key, subdomain, and location_id as we did with the /patients endpoint

   

3. We will then also include John’s patient ID to the patient_id field and we will also add "updated_at" to the sort field

   

4. After that, click the “Try It!” button to make the API call - you should receive a response that looks similar to this:

   

5. From here, we are going to grab each of the charge’s IDs as well as the dollar amount associated with them and add those values to the spreadsheet - click each tab below to see what each API response and spreadsheet cell will look like

   

Step 3: Posting a Payment

Now that we have collected the patient’s ID and a list of their charges, we have almost everything that we need to insert our payment into Open Dental to pay off this patient’s balance.

In this section we will grab the last few things that we need and then make the payment.

Collect a Payment Type ID

Use the reference link in the provided spreadsheet associated with the payment type ID row to go to the documentation for making a GET /payment_types request.

For this endpoint, we will just need the API key, subdomain, and location_id.

After sending the request, we will grab the payment type ID for the “Credit Card” payment type.

Designate a Transaction ID

Now we need to designate an ID for the payment that we are making here. Unlike many other IDs used through the NexHealth API, the transaction ID is a string that is chosen by the API caller.

In this case, for sake of simplicity, we will use the ID “test-transaction-id”.

Post the Payment Through the Nexhealth API

Now we are ready to post the payment through the API. Here is the link to the documentation page where we will do this from: https://docs.nexhealth.com/reference/postpayments.

1. Start by entering the API key, subdomain, and location ID

   

2. Next, expand the “PAYMENT OBJECT” section

   

3. Next, let's add the patient_id, amount (which will be negative because we are decreasing the patient’s balance), payment_type_id, and transaction_id

   

   For this payment, we will be paying off the balance for all three procedures associated with the patient at once.

   We have already specified the total amount that this payment will be for; however, we now need to break down which charges/procedures this payment is for as well as how much we are allocating for each charge.

4. To do this, click on the “CHARGE_SPLITS OBJECT” button

   

5. Next, we will click “ADD FIELD” three times (once for each charge)

   

   At this point, the charge_splits object section should look like this:

   

6. Now we are going to replace the “newKey” strings with the charge IDs, and the “New Value” strings with the charge amounts (these should be negative). Your charge_splits object should look like this:

   

7. We are now finished building the API request - go ahead and click the “Try It!” button and you should receive a successful response from the API

Validate that the Payment is in the Open Dental Ledger

Now return to John’s ledger within Open Dental (you may need to click to another page and come back to refresh it) and you will see the payment has been posted.

Onward toward production

Once you are ready to start making production API calls using our Ledger/Financial endpoints, please reach out to [email protected], as action will be needed from our team for your production API key to be used for pulling Ledger/Financial data.