Getting started

Tyro HealthPoint lets a practice management system (PMS) process private health fund claims through a Tyro terminal. The PMS builds and validates the claim, including provider details, patient identifiers and the claimable service items. The terminal is used to capture the patient's health fund details and send the claim to the fund for approval.

Before you begin, review the certification criteria, which set out the minimum requirements for certifying an integrated private health fund solution with Tyro: Certification Criteria for iClient Health.

Two claiming functions are available on both libraries:

Claim — submit a claim to the patient's health fund.
Cancel claim — cancel an approved claim on the day it was processed.

The JS library also supports a rebate estimate and preferred provider claims.

How a claim works

In the PMS, the staff select a provider and a patient and build up the list of services provided.
Once the list is final, the PMS invokes the library, passing in the claim items and some other details.
The library's window appears and the claim is passed to the terminal for processing.
The patient presents their health fund card on the terminal when prompted, and the claim is sent to the health fund for approval.
Once approved, the terminal prints the claim receipt and shows the gap amount to the patient.
In the PMS, the library shows the gap amount and asks the operator to Accept or Reject the claim.
- Accept prompts the terminal to print the patient copy and finalise the claim.
- Reject prompts the terminal to void the claim and print receipts showing it has been voided.
In either case, the result of the original claim is returned to the PMS.

The operational workflow page covers claim approval, declines, voids and cancellations in more detail.

Refer to the JS library API for sample HealthPoint claiming code. After downloading and extracting the zip folder, open iclient-api/index.html, click Classes, then TYRO.IClientWithUI, scroll down to the index and method tabs, and click index.

Claim request

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

Request parameter	Type	Description
`claimItems`	String	JSON array of claim items (maximum 16). See the claim items table below.
`claimItemsCount`	int	Total number of claim items.
`mid`	Integer	Optional. Required for headless pairing, multi-merchant, or if your browser doesn't support local storage.
`tid`	Integer	Optional. Required for headless pairing, multi-merchant, or if your browser doesn't support local storage.
`integrationKey`	String	Use if your browser doesn't support local storage, or for headless pairing or multi-merchant.
`providerId`	String	The 8-character provider number (usually Medicare issued).
`serviceType`	String	The 1-character category of service. See Modalities and settlement.
`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 completed on the terminal.
`statusMessageCallback`	Function	Invoked to advertise what is happening on the terminal, which typically faces the customer rather than the provider.
`questionCallback`	Function	Invoked when the terminal requires the merchant to answer a question to proceed with the transaction.

statusMessageCallback and questionCallback are only required when using TYRO.IClient. With TYRO.IClientWithUI, the UI provided handles status messages and questions.

Claim items

Claim item field	Type	Description
`serviceReference`	String	Optional clinical reference or tooth number suffix (maximum 3 characters). See Service reference.
`claimAmount`	int	Claim amount in cents (maximum 10 digits).
`serviceDate`	String	Claim date, in `YYYYMMDD` format.
`description`	String	Item description for the receipt (maximum 32 characters).
`serviceCode`	String	Item number or service code (maximum 5 characters).
`patientId`	String	Patient identifier (exactly 2 digits).

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
});

Callbacks

To handle the response:

Code callback functions to handle the responses returned by the library through statusMessageCallback, questionCallback and transactionCompleteCallback.
Associate the callback functions with the callbacks in the function invocation.
Use the response fields returned by the callback to control any subsequent workflow in the PMS, for example using the result field to decide when the PMS closes the transaction, displays the result, and marks the transaction with the correct status, such as "Approved".
Conduct all follow-up actions and workflows in the callback function.

statusMessageCallback is called with a single string argument, for example "Patient Approval".

questionCallback may not apply to every transaction. For a claim, it can include a prompt for the patient to approve or decline the claim. It is called with:

Field	Type	Description
`text`	String	The question to present to the merchant.
`options`	Array[String]	The button labels to present. Show one button for each element.
`answerCallback`	Function	Call this with the label of the clicked button, from the `options` array, to answer the question.

Claim response

Claim responses typically return within 5 seconds but can take up to 55 seconds with some funds. If no response arrives within 55 seconds, the terminal sends an auto void and the claim must be reattempted.

Field	Description
`result`	The overall transaction result: `APPROVED`, `CANCELLED`, `REVERSED`, `DECLINED`, `SYSTEM ERROR`, `NOT STARTED` or `UNKNOWN`. The provider only receives settlement if this is `APPROVED`. `UNKNOWN` means the provider should look at the terminal to determine what happened, and typically indicates a network error.
`transactionId`	The 36-character ID for the integrated transaction.
`healthpointFreeText`	Optional text from the health fund. Can include the patient name, policy details or loyalty information.
`healthpointGapAmount`	The aggregate gap amount.
`healthpointHealthFundName`	The health fund name.
`healthpointPhfResponseCode`	The claim level response code.
`healthpointRefTag`	A unique claim identifier, printed on the receipt.
`healthpointSettlementDateTime`	The settlement timestamp from HealthPoint.
`healthpointTerminalDateTime`	The terminal's local timestamp.
`healthpointTotalBenefitAmount`	The aggregate benefit amount.
`healthpointClaimItems.rebateAmount`	The benefit amount for the service item.
`healthpointClaimItems.responseCode`	The service item response code.
`healthpointClaimItems.responseCodeDescription`	The service item response short description.

Other elements echo the request. Every response other than 00 - APPROVED means the fund declined the item, although an item with another response code can still pay a limited benefit. See the response codes for each type of response.

Loyalty and bonus codes

For some funds, such as HCF, the response can include a benefit-only item code that the PMS didn't submit, as part of the fund's loyalty or bonus program. It reduces the gap the patient owes. The code appears on the patient and provider receipts with:

a $0 charge amount
a benefit-only amount
the item serviceCode 00992
possibly more detail in 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 Consult",
            "serviceReference": "01",
            "patientId": "02",
            "serviceDate": "20240921",
            "responseCode": "0000"
        }
    ],
    "healthpointGapAmount": "4400",
    "healthpointPhfResponseCode": "00",
    "healthpointPhfResponseCodeDescription": "APPROVED",
    "healthpointHealthFundName": "ISOFT FUND",
    "healthpointHealthFundIdentifyingDigits": "0099"
}

Gap payments

Once a claim is approved, there's typically a gap between the benefit the health fund pays and the amount the practitioner charged. If the patient wants to pay the gap by card, use the standard purchase method and pass healthpointTransactionId, which is the transactionId returned in the response to the original HealthPoint claim. See Payments, cashout and refunds.

Cancel a claim

An approved claim can be cancelled on the day it was processed, before settlement (23:59:59 Australian Eastern time, adjusted for daylight saving).

cancelHealthPointClaim(requestParams, transactionCallbacks) tells the terminal to cancel a HealthPoint claim. The request parameters are those of the claim, plus refTag. The claim values must match the original claim.

Request parameter	Type	Description
`claimItems`	String	JSON array of claim items (maximum 16). Must be the same as the original claim.
`claimItemsCount`	int	Total number of claim items. Must be the same as the original claim.
`mid`	Integer	Optional. Must be the same as the original claim if set.
`tid`	Integer	Optional. Must be the same as the original claim if set.
`integrationKey`	String	Must be the same as the original claim if set.
`providerId`	String	The 8-character provider number. Must be the same as the original claim.
`serviceType`	String	The 1-character category of service. Must be the same as the original claim.
`totalClaimAmount`	int	The total amount of all claim items, in cents. Must be the same as the original claim.
`refTag`	String	Required. The `healthpointRefTag` returned in the original claim's final transaction status response.
`transactionid`	String	Optional. Supply a custom transaction ID. Must be different from the original claim.
`transactionCompleteCallback`	Function	Invoked when the transaction has completed on the terminal.
`statusMessageCallback`	Function	Invoked to advertise what is happening on the terminal.
`questionCallback`	Function	Invoked when the terminal requires the merchant to answer a question.

// Cancel a completed HealthPoint claim with two claim items totalling $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
});

Item numbers

Item numbers for claims must be known to and provided by the PMS. They change from time to time, typically on 1 April, and vary between health funds, so the PMS is responsible for providing the authoritative list to practice installations. The HealthPoint reference data lists the currently approved item numbers by modality, plus error codes and the items configured for testing:

A category code is included in the reference data, but the PMS doesn't need to set it.

Service reference

Each claimable item has an optional 3-character service reference. Professions use it to list the elements certain funds need for a claim. The HealthPoint reference data has the specific codes. In summary:

Psychology: the primary condition, as 2 numeric characters.
Occupational therapy: the primary condition as 1 numeric character and the diagnostic intervention as 1 numeric character.
Physiotherapy and chiropractic: the body part or clinical code, as 2 alphanumeric characters.
Dentistry: the FDI tooth number, as 2 numeric characters.
Other professions: up to 3 alphanumeric characters.

Next steps

Operational workflow
Modalities and settlement
Supported health funds
Reports and reconciliation
Testing
Multi-merchant, for practices where several providers share a terminal