Integrated Private Health Fund Claiming

Introduction

This document outlines the implementation process for integrating private health fund claiming into Practice Management Software (PMS) using the Tyro HealthPoint system. It is intended for software developers and integration specialists and covers:
  1. Overview
  2. iClient API
  3. Claim Requests
  4. Callbacks
  5. Claim Response
  6. Claim Cancel
  7. Testing and Demo

Overview

The PMS is responsible for building and validating claim payloads, including provider details, patient identifiers, and claimable service items. The terminal is used only to capture patient health fund member details via swipe or tap.

Once the claim payload has been drafted, the PMS invokes iClient passing in the list of claim items (in JSON format) along with some other details. The iClient window appears, and the claim is passed through to the terminal for processing. The patient swipes or taps their health fund card in the terminal when prompted, and the claim is sent off to the appropriate health fund for approval. Once approved, the terminal prints the claim receipt and shows the gap amount to the patient. On the PMS, iClient shows the gap amount and asks the operator to Accept or Reject the claim. Pressing the Accept button prompts the terminal to print the patient copy and finalise the claim. Pressing the Reject button prompts the terminal to void the claim and print receipts showing that the claim has been voided. In either case, the result of the original claim is returned to the PMS.

Before beginning development, review the Certification Criteria for iClient Health for minimum requirements.

iClient API

Refer to iClient API for sample HealthPoint claiming code. After downloading and extracting the zip folder, navigate to iclient-api/index.html, then Classes > TYRO.IClientWithUI. At the top left corner underneath the APIs, click on Classes, and then click on TYRO.IClientWithUI, scroll down until you see the index and method tabs, then click on index.

Claim Requests

Claim Payloads

The iClient API for Private Health Fund claims requires specific parameters, including a JSON claim payload. For cancellations, use the same payload as the original claim, and can only be performed on the same day.

HealthPoint Claiming Implementation

initiateHealthPointClaim(requestParams, transactionCallbacks) - Tell the terminal to start a HealthPoint claim.

Request Parameters

Request Parameters Type Description
claimItems String JSON array of claim items (max 16)
claimItemsCount int Total number of claim items
mid Integer Optional - Required for headless pairing, multi-merchant, or if your browser does not support local storage
tid Integer Optional - Required for headless pairing, multi-merchant, or if your browser does not support local storage
integrationKey String Use if your browser does not support local storage, headless pairing or multi-merchant as a feature
providerId String 8-character provider number (usually Medicare issued)
serviceType String 1-character category of service. See table below
totalClaimAmount Int The total amount of all claim items in cents
transactionid String Optional - Supply a custom transaction ID
transactionCompleteCallback Function Invoked when the transaction has been completed on the terminal
statusMessageCallback* Function Invoked to advertise what is happening on terminal, which is typically facing the customer rather than the provider
questionCallback* Function Invoked when the terminal requires the merchant to answer a question in order to proceed with the transaction

claimItems Table

Claim parameter Type Description
serviceReference String clinical reference or tooth number suffix. See reference below. (max 3 chars)
claimAmount int Claim amount in cents (max 10 digits)
serviceDate String Claim date (YYYYMMDD format)
description String Item description for receipt (max 32 chars)
serviceCode String Item number or service code (max 5 chars)
patientId String Patient identifier (exactly 2 digits)

Item Numbers

The PMS is responsible for maintaining and providing the item numbers for claims. Refer to the HealthPoint reference data for currently approved item numbers. Note that item numbers may change annually, typically on April 1st. Reference HealthPoint reference data for currently approved item numbers by modality.

Service Reference

Each claimable item has an optional 3-character serviceReference. This field is used by various professions to list elements required for claims with particular funds. Refer to the HealthPoint reference data for specific codes. This includes:

  • Psychology: Primary condition as 2 numerical characters
  • Occupational Therapy: Primary condition as 1 numeric character and Diagnostic Intervention as 1 numeric character
  • Physiotherapy and Chiropractic: Body part / Clinical code as 2 alphanumeric characters
  • Dentistry: FDI Tooth number as 2 numerical characters
  • Other professions: up to 3 alphanumeric characters

Details of these codes can be found in the HealthPoint reference data document.

Modalities

Modalities represent various types of health services. The serviceType field in the claim payload should contain the appropriate modality code. Reference HealthPoint reference data for modalities supported by each Health Fund. Modalitied include:

Modality Description
0 Dental Technician
1 Osteopath
3 Endodontist
4 Oral Surgeon
5 Orthodontist
6 Paedodontist (Paediatric)
7 Periodontist
8 Prosthodontist
B Acupuncturist / Chinese Medicine
C Chiropractor
D General Dentist
E Dietitian
F Podiatrist
G Medical Doctors (including GP claims for overseas cover)
H Occupational Therapist
J Myotherapy
M Remedial massage therapist
O Optometrist
P Physiotherapist
Q Counselling
S Speech Pathologist
U Exercise Physiology
V Audiology
Y Psychologist
Z Optical Dispenser

Health funds supported by Tyro HealthPoint

Note this includes funds that support both Private Health Insurance. Some funds also support Overseas Visitors and Overseas Student Cover claims.

Health Fund Name Health Fund ID Identifying Digits
ACA PHF00010 0012
ADF Family Health PHF00510 0109
AHM PHF00550 0041
AIA PHF00420 0138
Australian Unity PHF00040 0008
BUPA PHF00300 0007
~BUPA~ ~PHF00260~ ~0006~
~BUPA~ ~PHF00370~ ~0003~
CBHS PHF00070 0009
CBHS Corporate Health PHF00075 0139
Credicare (See-U by HBF) PHF00060 0045
Defence PHF00030 0020
Doctors Health Fund PHF00020 0005
EMERGENCY SERVICES HEALTH PHF00470 0140
~GMF Health~ (merged with HBF) ~PHF00110~ ~0040~
GMHBA/FRANK/BUDGET PHF00100 0042
HBF PHF00180 0025
HCF PHF00200 0015
HCI PHF00140 0013
~health.com.au~ (merged w/GMHBA) ~PHF00500~ ~0125~
Health Partners PHF00450 0024
HIF PHF00160 0026
Latrobe PHF00220 0038
Lysaght / Peoplecare PHF00230 0016
Medibak Private PHF00240 0004
Navy PHF00310 0010
nib (including brands AAMI, APIA, Australian Seniors, IMAN, ING Health, Priceline health insurance, QANTAS, Real Health insurance and Suncorp) PHF00290 0002
onemedifund (National Health Benefits Australia) PHF00460 0088
Phoenix Health PHF00330 0019
Police PHF00380 0021
QLD Country PHF00280 0022
Reserve Bank Health Society PHF00350 0089
RT / Transport Health PHF00350 0084
St Lukes / Astute Simplicity PHF00390 0044
Teachers UniHealth PHF00320 0011
TUH PHF00340 0018
Westfund PHF00440 0096
isoft Fund (for testing only) PHF00999 0099

Note: The test health fund (ISOFT Fund) is PHF00999 and has identifying card digits of 0099 and only works in non-production environments.

Current list of supported funds by provider modality

Reference the following Excel doc for a list of item codes and responses for each supported fund and modality: HealthPoint reference data

Note: A category code is included in the reference data but does not need to be set by the PMS.

Health funds not currently supported by Tyro HealthPoint

  • CDH (Hunter Health Insurance)
  • GU Health * under migration to nib
  • MDHA (Mildura Health Fund)

Example request

Copy
Copied
iclient.initiateHealthPointClaim({
    providerId: "1455813F", 
    serviceType: "P", 
    claimItemsCount: "2", 
    totalClaimAmount: "20100", 
    claimItems: [
        {
            "claimAmount": "10000",
            "serviceCode": "500",
            "description": "Assessment Consult",
            "serviceReference": "01",
            "patientId": "02",
            "serviceDate": "20240921"
        },
        {
            "claimAmount": "10100",
            "serviceCode": "505",
            "description": "Subsequent Consult",
            "serviceReference": "01",
            "patientId": "02",
            "serviceDate": "20240921"
        }
    ]}, {
    transactionCompleteCallback: yourPosCode.handleComplete,
    statusMessageCallback: yourPosCode.handleStatusMessage,
    questionCallback: yourPosCode.questionAsked
});

transactionCallbacks

Callback functions that are only required when using TYRO.IClient. When using TYRO.IClientWithUI, status messages and questions are handled by the UI provided.

Steps to follow

The steps to be followed to handle the response are given as follows:

  1. You are required to code callback functions to handle the responses returned by iClient via the statusMessageCallback , the questionCallback , and the transactionCompleteCallback . Examples of callback functions are given in the below.
  2. You must associate the callback functions that you have created with the callbacks in the function invocation.
  3. The PMS must use the response fields returned by the callback, and use them to control any subsequent workflows within the PMS e.g. using the result field to control when the PMS closes the transaction off, displays the result on the screen, and mark the transaction in the correct status e.g. "Approved".
  4. The PMS must conduct all follow-up actions/workflows in the callback function.

transactionCompleteCallback Function:

Callback Name Type Description
transactionCompleteCallback Function Invoked when the transaction has been completed on the terminal.

statusMessageCallback Function:

Callback Name Type Description
statusMessageCallback Function Invoked to advertise what is happening on terminal, which is typically facing the customer rather than the merchant. Called with a single String argument. For example "Patient Approval".

questionCallback Function:

Callback Name Type Description
questionCallback Function Invoked when the terminal requires the merchant to answer a question in order to proceed with the transaction. This may include a prompt for the patient to Approve or Decline a claim

Question Callbacks may not be applicable for all transactions. However, when

Field Type Description Usage Required
text String The question message to present to the merchant. Required (if the callback itself is being used.)
options Array[String] The set of button labels to present. A button should be presented to the merchant for each element in this array. Required (if the callback itself is being used.)
answerCallback Function The callback to be used to provide the merchant's answer to the question. The PMS should call this function when the merchant clicks one of the buttons passing the label of the clicked button (from the options array in the question). Required (if the callback itself is being used.)

Claim Response

Claim responses are typically returned within 5 seconds but may take up to 55 seconds with some funds. If a response is not returned within 55 seconds, the terminal will send an Autovoid and the claim must be reattempted.

Key response fields:

Field Description
result Overall transaction result as one of the following values: APPROVED, CANCELLED, REVERSED, DECLINED, SYSTEM ERROR, NOT STARTED, UNKNOWN. The provider will only receive settlement if this value is APPROVED. UNKNOWN means the provider should look at the terminal to determine what happened. Typically this would indicate a network error.
transactionId The 36 character id for an integrated transaction
healthpointFreeText Optional text returned from the health fund - can include patient name, policy details or loyalty information
healthpointGapAmount Aggregate Gap amnount
healthpointHealthFundName Health fund name
healthpointPhfResponseCode Claim level response code
healthpointRefTag A claim unique identifier printed on the receipt
healthpointSettlementDateTime Settlement timestamp from HealthPoint
healthpointTerminalDateTime Terminal local timestamp
healthpointTotalBenefitAmount Aggregate benefit amount
healthpointClaimItems.rebateAmount Service item benefit amount
healthpointClaimItems.responseCode Service item response code
healthpointClaimItems.responseCodeDescription Service item response short description

Other elements will echo the request submission.

All responses except "00 - APPROVED" mean the item has been declined by the fund. Items may return a response code other than '00' and still pay a limited beneifit. Reference Response codes for details on each type of response.

Loyalty and bonus codes

For select funds like HCF, it's possible to receive back an additional benefit only item code not submitted by the PMS as part of a Health Fund loyalty or bonus program. This benefit only item code will reduce the gap owed by a patient. The code will be displayed on patient and provider receipts with:

  • $0 charge amount
  • a benefit only amount
  • item serviceCode '00992'
  • additional detail may be returned in the field healthpointFreeText, such as "Limit Boost"

Example response

Copy
Copied
{
"result": "APPROVED",
    "transactionId": "6dbdaffd58adac4e89387f2c9d2c0cdd7c1e",
    "healthpointRefTag": "2120599",
    "healthpointTotalBenefitAmount": "6600",
    "healthpointSettlementDateTime": "20240921093316",
    "healthpointTerminalDateTime": "20240921093316",
    "healthpointMemberNumber": "12345678",
    "healthpointProviderId": "2147661H",
    "healthpointServiceType": "P",
    "healthpointClaimItems": [
        {
            "claimAmount": "1000",
            "rebateAmount": "600",
            "serviceCode": "00500",
            "description": "Assessment Consult",
            "serviceReference": "01",
            "patientId": "02",
            "serviceDate": "20240921",
            "responseCode": "0000"
        },
        {
            "claimAmount": "10000",
            "rebateAmount": "6000",
            "serviceCode": "00520",
            "description": "Extended Consul",
            "patientId": "02",
            "serviceDate": "20240921",
            "responseCode": "0000"
        }
    ],
    "healthpointGapAmount": "4400",
    "healthpointPhfResponseCode": "00",
    "healthpointPhfResponseCodeDescription": "APPROVED",
    "healthpointHealthFundName": "ISOFT FUND",
    "healthpointHealthFundIdentifyingDigits": "0099"
}

Gap Payments

Once a claim has been approved, there is typically a gap between the benefit amount paid by the health fund and the amount charged by the practitioner. If the patient would like to use a card to pay for the gap amount, the standard purchase method can be used to process the payment. Please be sure to pass in the healthpointTransactionId which is the transactionId returned in the response to the original HealthPoint claim.

Settlement

An aggregated single settlement (aside from HCF who issues a separate settlement) is issued by HealthPoint to the provider the following business day for all approved claims. The settlement claims period is 00:00:00 to 23:59:59 Australian Eastern time, adjusted for daylight savings.

Claim Cancel

An Approved Claim can be cancelled on the same day it was processed prior to settlement (23:59:59 Australian Eastern Time, adjusted for daylight savings).

HealthPoint Claim Cancel Implementation

cancelHealthPointClaim (requestParams, transactionCallbacks) - Tell the terminal to cancel a HealthPoint claim.

Request Parameters

Request Parameters Type Description
claimItems String JSON array of claim items (max 16) - must be same as original claim
claimItemsCount int Total number of claim items - must be same as original claim
mid Integer Optional - must be same as original claim if set
tid Integer Optional - must be same as original claim if set
integrationKey String must be same as original claim if set
providerId String 8-character provider number - must be same as original claim
serviceType String 1-character category of service - must be same as original claim
totalClaimAmount Int The total amount of all claim items in cents - must be same as original claim
refTag String The reference tag (healthpointRefTag) returned in the original claim's final transaction status response - required
transactionid String Optional - Supply a custom transaction ID. Must be different from the orignal claim
transactionCompleteCallback Function Invoked when the transaction has been completed on the terminal
statusMessageCallback* Function Invoked to advertise what is happening on terminal, which is typically facing the customer rather than the provider
questionCallback* Function Invoked when the terminal requires the merchant to answer a question in order to proceed with the transaction

Example Claim Cancel

Copy
Copied
// to initiate a cancel of a completed healthpoint claim with two claim items totaling $250
iclient.cancelHealthPointClaim({providerId: "2147661H", serviceType: "D", claimItemsCount: "2", totalClaimAmount: "25000", refTag: "0960001", claimItems: [
        {
            "claimAmount": "10000",
            "serviceCode": "00001",
            "description": "SKULL XRAY",
            "serviceReference": "01",
            "patientId": "02",
            "serviceDate": "20131010"
        },
        {
            "claimAmount": "15000",
            "serviceCode": "00001",
            "description": "SKULL XRAY",
            "serviceReference": "01",
            "patientId": "02",
            "serviceDate": "20140508"
        }
    ]}, {
   transactionCompleteCallback: yourPosCode.handleComplete,
   statusMessageCallback: yourPosCode.handleComplete,
   questionCallback: yourPosCode.questionAsked
 });

Testing and Demo

Use the Tyro non-production integration environment and development terminals to test HealthPoint integrations. A set of test health fund cards can be issued by Tyro - contact your partnerships manager for details.

The following patient and provider details can be used for tests:

Patient IDs on Card:

  • 00 John Citizen
  • 01 Judy Citizen
  • 02 Jack Citizen

Provider details:

Name Provider Number Service Type
Katy Cobrin 2159081W P
Leonore Marsh 1455813F P

HealthPoint Claiming Demo

Demo - JS Fiddle

warning

Please don't click on the Save button if you make any changes in the JS Fiddle sample app. Instead, please press run if you have made any changes. If you click save, it may break sample functionality.

Copyright © Tyro Payments 2019-2022. All right reserved.