Integrated Private Health Fund Claiming
Introduction
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
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:
- 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.
- You must associate the callback functions that you have created with the callbacks in the function invocation.
- 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".
- 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
{
"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
// 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
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.