Guides

Get started with payments

Suggest Edits

This guide will help you use NexHealth’s API to collect outstanding patient payments and record payment details in health record system ledgers.

The guide is written with the assumption that you already have a bearer token and have access to our financial endpoints. If you don't, check out our token authentication document, and email [email protected] for endpoint access.

Overview

To build a digital patient payments application, you'll likely need to:

  • Know who to charge.
  • Know how much to charge.
  • Collect payments.
  • Record payment details in the health record system.

Step 1: Determine who to charge

A guarantor is the person fiscally responsible for a patient. One guarantor may be responsible for multiple patients.

To determine a patient's guarantor, call get patients and see the guarantor_id field. If the value is '0', the patient is their own guarantor.

{
  "code": false,
  "description": "Description",
  "error": "Error",
  "data": [
    {
      "id": 415,
      "email": "[email protected]",
      "first_name": "John",
      "middle_name": "Anthony",
      "last_name": "Smith",
      "guarantor_id": 0,
      "bio": {
        "city": "New York",
        "state": "NY",
        "gender": "Female",
        "zip_code": "20814",
        "new_patient": false,
        "non_patient": true,
        "phone_number": "5163042196",
        "date_of_birth": "1964-05-03",
        "address_line_1": "",
        "address_line_2": "",
        "street_address": "",
        "cell_phone_number": "",
        "home_phone_number": "",
        "work_phone_number": ""
      },
		...
	}
 ]
}

If a patient isn't their own guarantor, call get patients/{id} with the guarantor_id. Record the guarantor's name and contact information for later use.

Step 2: Determine how much to charge

There are two ways you can determine how much to charge. The first approach is simpler and gives you the guarantor's total balance across all their dependents. The second approach gives you an individual patient's balance and is useful if you want to construct itemized invoices.

🚧

Wait for insurance claims to be settled

NexHealth recommends computing and collecting outstanding balance after insurance claims have been settled to ensure you request the correct amount.

Approach 1: Get guarantor balance

Call get guarantor_balances/{id} with the id found above. 

curl --request GET \
     --url 'https://nexhealth.info/guarantor_balances/{GUARANTOR_ID}?subdomain=YOUR_SUBDOMAIN&location_id=YOUR_LOCATION' \
     --header 'Nex-Api-Version: v20240412' \
     --header 'Accept: application/vnd.Nexhealth+json;version=2' \
     --header 'Authorization: Bearer YOUR_BEARER_TOKEN'

The guarantor_portion field indicates how much the guarantor should be charged. 

{
  "code": false,
  "description": "Description",
  "error": "Error",
  "data": {
    "id": 113,
    "foreign_id": "1",
    "guarantor_id": 115,
    "location_id": 115,
    "write_off_estimate": {
      "amount": "62.00",
      "currency": "USD"
    },
    "total_balance": {
      "amount": "62.00",
      "currency": "USD"
    },
    "insurance_estimate": {
      "amount": "62.00",
      "currency": "USD"
    },
    "guarantor_portion": {
      "amount": "62.00",
      "currency": "USD"
    },
  ...
}

Approach 2: Calculate patient balance

Call get charges, get payments, and get adjustments with the patient's id to see all charges, payments, and adjustments related to the patient.

curl --request GET \
     --url 'https://nexhealth.info/charges/{PATIENT_ID}?subdomain=YOUR_SUBDOMAIN&location_id=YOUR_LOCATION' \
     --header 'Nex-Api-Version: v20240412' \
     --header 'Accept: application/vnd.Nexhealth+json;version=2' \
     --header 'Authorization: Bearer YOUR_BEARER_TOKEN'    

curl --request GET \
     --url 'https://nexhealth.info/payments/{PATIENT_ID}?subdomain=YOUR_SUBDOMAIN&location_id=YOUR_LOCATION' \
     --header 'Nex-Api-Version: v20240412' \
     --header 'Accept: application/vnd.Nexhealth+json;version=2' \
     --header 'Authorization: Bearer YOUR_BEARER_TOKEN'    

curl --request GET \
     --url 'https://nexhealth.info/adjustments/{PATIENT_ID}?subdomain=YOUR_SUBDOMAIN&location_id=YOUR_LOCATION' \
     --header 'Nex-Api-Version: v20240412' \
     --header 'Accept: application/vnd.Nexhealth+json;version=2' \
     --header 'Authorization: Bearer YOUR_BEARER_TOKEN'

Calculate the patient portion by summing all charge.fee.amount, payment.payment_amount.amount, adjustment.adjustment_amount.amount values, and subtracting all charge.write_off_total values.

Step 3: Collect payments

Now that you have the balance and contact information, you can request and collect payments.

NexHealth doesn't provide payment processing or messaging endpoints. If you want to process payments or send messages, use third party vendors.

Step 4: Record payment details

Once the guarantor has paid, use the post payment_transactions endpoint to add the payment details to the ledger.

curl --request POST \
     --url 'https://nexhealth.info/payment_transactions?subdomain=YOUR_SUBDOMAIN&location_id=YOUR_LOCATION' \
     --header 'Nex-Api-Version: v20240412' \
     --header 'Accept: application/vnd.Nexhealth+json;version=2' \
     --header 'Authorization: Bearer YOUR_BEARER_TOKEN' \
     --header 'Content-Type: application/json' \
     --data '
{
     "payment_transaction": {
          "patient_id": "YOUR_PATIENT",
          "amount": "YOUR_AMOUNT",
          "type_name: "YOUR_PAYMENT_TYPE",
          "transaction_id": YOUR_TRANSACTION_ID
}
'

To associate payments with either providers or charges, use the provider_splits and charge_splits fields. The splits can't exceed the total payment amount.

Transaction_id is client generated id; you can pass in any value as long as it hasn't been used for a post payment_transactions call before. The parameter has two functions:

  • Idempotency: It ensures payment inserts are idempotent (i.e it prevents the same insert from happening multiple times).
  • Tracking: If you split a payment across either charges or providers, a single post request may create multiple payment records in the patient's ledger. When you later call get payments, the transaction_id field will help you see which payment records were apart of the same post request. Transaction_id isn't visible in the health record system UI.

🚧

Inserts are asynchronous

Payment inserts happen asynchronously and can fail. Subscribe to the payment_transaction_insertion webhook event to get notified when the insert completes.

Updated about 14 hours ago