Program API

Overview

The Program API is used to communicate between HICAPS and a Program (or scheme or fund) for the purpose of determining the funding result for claims submitted by billers. To facilitate this communication, the Program API comprises a set of webhooks and RESTful API resources for consumption.

Claiming Overview

Philosophy

The Program API is event-driven. The philosophy behind this approach are based on three principles:

  1. Flexible decision making process by program.
  2. Visibility/clarity during decision making process for provider. Providers will have access to the most real-time status of their claims.
  3. Empower provider to determine how long they want to wait for decisions. An example is that the provider is able to request an invoice cancellation while the invoice is still pending.

Definitions

Programs

The program, or fund, or scheme, is the entity adjudicating and funding the claims on the invoice.

The programs that HICAPS is connected to is defined below. Note this list is continually being updated.

Program Codes
Program Code Program Name Program Website HICAPS Terminal Required?
medicare-bulkbill Medicare - Bulk Bill Medicare Bulk Bill External Link No
medicare-dva Medicare - Dept. Veteran Affairs (DVA) / Dept. Veteran Affairs - Allied (VAA) Medicare DVA External Link No
medicare-pci Medicare - Patient Claiming Interactive Medicare Claims Online External Link No
medicare-easyclaim-pc Medicare - Easyclaim - Patient Claims (Electronic) Medicare Easyclaim - Patient Claims External Link Yes
medicare-easyclaim-bulkbill Medicare - Easyclaim - Bulkbill Medicare Easyclaim - Bulkbill External Link Yes
ndis-agency National Disability Insurance Scheme API www.ndis.gov.au External Link No
tac Transport Accident Commission www.tac.vic.gov.au External Link No
wsv WorkSafe Victoria www.worksafe.vic.gov.au External Link No
mpl Medibank Private Limited www.medibank.com.au External Link No
nib nib Health Fund www.nib.com.au External Link No
wcq WorkCover Queensland WorkCover QLD External Link No
icwa Insurance Commission of Western Australia www.icwa.wa.gov.au External Link No
icare Insurance and Care NSW www.icare.nsw.gov.au External Link No

Billers and Providers

A biller is the entity making the claim and receiving payment. The biller applies for access to a Program and is authorised and identified by the Program.

The program cannot edit the biller’s details (the biller updates their own details using the HICAPS interface). However, the program can read the Billers details and change the biller’s status with the program.

A provider is the entity providing the service to the patient.

Programs can have different requirements in relation to Providers:

  1. Program requires the provider information to be submitted with each claim.
  2. Program does not require any provider information, in which case the provider information is optional with the claim.

Members and Patients

A member is a person that has membership with a program. A patient is the person receiving the product or service from a provider. Ususally these are the same person but sometimes they may be different.

For example a parent may be a member of a health fund and their child may be listed on their membership but is not a member in their own right. If the child is receiving treatment, then in this case the member would be the parent and the patient is the child.

A member is defined at the invoice level, as defined in the Member Paramters section.

A patient is defined at the claim level (i.e. line item), as defined in the Patient Parameters section.

Invoices and Claims

An Invoice is a holistic representation of the data submitted to the Program. An Invoice contains a collection of Claims, which represent line items on the Invoice. It is recommended that a program responds to all the claims on an invoice in one response.

Predeterminations

Predeterminations are similar in concept to a quote as a point-in-time “what if” assessment of the claim data submitted to the program if the member requests it. Predeterminations are not binding nor guaranteed and no payments are made from a predetermination - even if approved.

A program may store a record of the predetermination against a member’s profile for reference or visibility in a member app and so a predetermination should only be sent if the member requests a quote or estimate of the costs/coverage associated with the product or service that will be claimed.

The program will respond to the predetermination with their adjudication response to give the user an indication of what the program would respond with if that same data was submitted as an invoice.

See Predeterminations in the API Resources section for more technical information.

States, Statuses & Actions

States, statuses and actions are about providing as much context and information to the biller as possible as a claim progresses through the journey of adjudication and payment. They help facilitate a digital conversation between the biller and the program that occurs in real time via the API.

States

A claim can only be in one of the states defined by HICAPS. For example, a claim will move through states: submittedpendingapproved or rejected. If a claim is in the approved state then the biller can expect the next action is for a payment to be made and a payment notification triggered for that claim.

The program controls the state that a claim is in, and HICAPS stores a cache of the last known version of the state. Once the program changes the state of a claim (e.g. pendingapproved) they notify HICAPS and we immediately notify the biller.

See Claiming Process for more information on the claim submission flow.

Statuses

Status fields are available as part of the claim adjudication responses to add more information or context to the claim. These statuses are provided by the program and can be used to “overwrite” the claim state with a more specific/customised state that is displayed in a UI to the biller.

For example, a claim may be set to the pending claim state but this doesn’t tell the biller why the claim is pending. So, using statuses, the program may choose to indicate why the claim is in a pending state and to do this the program may pass back the below:

  • claimStatuses.statusTitle = Pending Review
  • claimStatuses.statusDescription = This claim is under review by a case manager and will be updated soon

This is a better and more specific representation of the state of the claim which, if provided, can be displayed to the biller instead of, or in addition to, the standard pending claim state.

Actions

Actions are a feature that allows the program to advise the provider that they are required to submit additional information, or take some other step(s), before an invoice can be processed. Similar to Statuses, this allows the program to provide extra context and information to the provider so they can perform the requried action(s).

For example, a program may require a treatment plan to be submitted for a member before they will adjudicate on the claim. To do this, the program may pass back the below:

  • actions.title = Submit Plan
  • actions.description = Please click here to submit a treatment plan for this member
  • actions.href = https://www.example.com/link/to/treatment/plan

Note: Actions are defined at the invoice level, not the claim level, because an action pending on any one claim could impact the adjudication of the whole invoice.

Claiming Process

The claiming process is generally broken down into two steps, explained in further detail in the sections below:

  1. Adjudication of a Claim - the program decides whether they will approve or reject a claim and how much they will pay, if anything
  2. Payment of a Claim - the biller is paid by the program

Adjudication of a Claim

As shown in the diagram below, the user submits a predetermination or an invoice for a program to HICAPS. HICAPS then sends all claims to the program for adjudication. Once the program has adjudicated on the claim they send an update back to HICAPS. HICAPS then notifies the user through a webhook with the updated status on the claims. This end to end process generally takes less than a second or two.

Note: A program may provide multiple status updates for any given invoice. For example they may respond with a pending status for the claim and then respond again later with an approved status for the claim.

Claiming Process Diagram
Claim States

On submission to the program, the State of each claim becomes pending. The claim flows through various states throughout its lifecycle. The state of the claim sets the user’s expectations around the timing and result of the claim payment. The program is the ‘source of truth’ for the state of the claim. As shown in the diagram below, most state transitions are initiated by the program performing API actions on HICAPS.

Claim States Diagram
Claim State Definitions
Adjudication Claim States

Claim states relating to normal adjudication flow.

State Enum Value Definition Biller’s expected reaction to the state
AWAITING RESPONSE awaitingResponse Claim has been submitted and is awaiting adjudication response from the Program. Biller expects this state to change immediately. Claim remaining in this state indicates that there could be communication problems on the Program’s end.
PENDING pending Program has received the claim and responding with pending to indicate they need more time to adjudicate. Biller is aware that invoice has been received by the program and is being processed. Biller can request cancellation or contact the Program if claim remains in pending state.
PROV. APPROVED provisionallyApproved Program has approved, but a change in decision is still possible (although unlikely). It is only required where there are separate systems involved in the approval and/or funding processes. Depends on the context:
  1. If the value is low and/or the provider is confident in dealing with the Program, they’ll accept it as Approved
  2. If the value is high and/or the provider isn’t confident, they’ll await the final result.

For example, the NDIS has an overnight adjudication process so the final approved should be expected the following business day.
REJECTED rejected Rejected by the Program or a delegated authority. Biller won’t expect payment. They will need to find another means to fund this claim (e.g. ask for payment from customer) or submit a new, valid, claim.
APPROVED approved The claim is approved and will be paid to the value of the specified benefit, which might be a full or partial funding amount. Biller expects to be paid in the next payment run to the value of the specified benefit
Cancellation Claim States

Claim states relating to cancellation flow.

State Enum Value Definition Biller’s expected reaction to the state
AWAITING CANCEL RESPONSE awaitingCancelResponse The biller has asked to cancel this claim, awaiting confirmation from Program that it is cancelled. Biller may wait for a short while to see if the cancellation is approved. They expect an update when the cancellation is confirmed.
CANCEL PENDING cancelPending The program has received the cancellation request but is not able to process it automatically. Program will send another update soon. Biller is aware that the cancellation request has been received and is being processed.
CANCELLED cancelled Program has processed the cancelation request and cancelled the claim in their system. Depends on the context:
  1. If payment has not been made yet, Biller expects to not be paid for this claim.
  2. If payment has been made, Biller may have to return funds to the program (process may vary by Program)
Payment Claim States

Claim states relating to payment flow.

State Enum Value Definition Biller’s expected reaction to the state
PAID paid The claim is paid to the specified benefit Biller expects the specified benefit to have been included in a recent payment to their bank account (within banking timeframes)
PAYMENT FAILED paymentFailed The payment for the claim has failed Biller expects to be contacted about how to rectify the payment details.

Payment of a Claim

This section describes the HICAPS payment process. Generally speaking HICAPS manages the payment process on behalf of the program, but this may not be the case for every program - see below.

  1. The “direct debit model” - HICAPS debits all programs the total amount of all their approved invoices for that day. HICAPS then credits each provider a single amount which covers all approved invoices for all programs on the direct debit model. This is the preferred and “default” payment model that most programs use.
  2. The “bureau model” - HICAPS disburses funds directly from the program’s bank account to the biller’s bank account. This means the biller will receive a single payment per program, per day. Only a small number of programs are on this model and this is no longer offered.
  3. The program pays the biller directly and HICAPS is not involved. Currently, only the NDIS, Medicare and Workcover QLD are on this model.

For HICAPS managed payments, #1 and #2 above, HICAPS will notify both the program, and the biller, about these payments so that finance systems can be kept reconciled. See the payments section for more detail.

Technical Overview

API Connection

All connections to HICAPS APIs must be using TLS v1.2 or higher.

API Message Headers

Certain HTTP headers must be provided when posting messages to the Program API, as shown below:

  • Content Type (Content-Type) - must be application/json
  • Content Length (Content-Length)
  • Host (Host)
  • Authentication (see below)

API Authentication

HICAPS’s Program API supports OAuth 2.0 authentication.

HICAPS provides an Oauth 2.0 Identity Provider endpoint. The API Consumer will be given a Client Id and Client Secret. These can be passed to the OAuth 2.0 endpoint using the client_credentials flow to obtain an access token which can be passed to HICAPS as a bearer token in the Authorization header

Each Program is considered a unique user of the API and will have their own API credentials which should not be shared.

HAL/HATEOAS

The HICAPS API uses HAL (Hypertext Application Language) to support a HATEOAS approach as defined by the REST specification.

In many cases, the URI of the resource will have been obtained from a webhook callback. In other cases, the URI of a resource can be found in the _links block of another resource.

Many HICAPS APIs are asynchronous. HICAPS will respond with 202 Accepted, and then signal via a webhook callback when the operation is completed or when the next step in the workflow is ready to be actioned.

API Response Codes

The HICAPS API may respond with any of the below status codes. This table gives guidance as to what the Program should do for a given status code.

Response Code Outcome
200 OK
  • Response payload should include the requested data
202 Accepted
  • HICAPS has accepted the request and will action.
  • HICAPS will raise another webhook if further interaction is required
4xx Client Error
  • The request has failed client input validation
  • The body will contain the API Error Payload
  • Log and investigate the request and resolve validation errors
  • Should only occur during development
5xx Server Error
  • HICAPS is experiencing technical issues
  • Retry the request as desired

API Error Payload

Where the API is responding with a HTTP 4xx Client Error, the body will contain the following data.

Field Format Required? Description
type string Conditional A link to online documentation describing the type of error.
title string Mandatory A description of the error.
invalidParams Array of Invalid Parameters Conditional An array of fields with errors

Invalid Parameters

Field Format Required? Description
name string Mandatory The field from the request which has caused the error.
Where the field was contained within an array, the format is arrayName[item].fieldName
Note: [0] is the first position in the array - see Example API Error Payload.
reason string Mandatory The reason for the error.

Example API Error Payload

{
    "type": "https://example.net/validation-error",
    "title": "Your request parameters didn't validate.",
    "invalidParams": [
        {
            "name": "claimStatuses[0].state",
            "reason": "'state' must not be empty."
        },
        {
            "name": "claimStatuses[2].benefit",
            "reason": "'benefit' must be a number."
        }
    ]
}

Webhooks

Webhooks allow HICAPS to signal to the Program that an event has occurred within the HICAPS platform. During initial configuration, the Program will specify the endpoint and authentication credentials for each webhook (some of which are optional).

Field Description
id A unique ID per event. This allows the Program to perform de-duplication in the event that the same event is signalled more than once.
HICAPS may sent the same event multiple times if it fails to get positive acknowledgement of a request.
created The date and time in Unix Epoch Time of the event.
data A block of data relevant to the event. The schema of the data block will vary for given webhook types.
Typically, the data block will contain both data properties and action properties, which will contain the URI of the possible HICAPS resource actions that may be carried out as a next step of processing the webhook.
type A string defining the type of the webhook
_links A set of links indicating the set of available operations related to this event

Webhook Standard Payload

Each webhook will have the following standard payload:

{
   "id": "{uuid}",
   "created": "{unix epoch time}",
   "data": "{data object}",
   "type": "{event type name}",
   "_links": {
      "lp:action": {
         "href": "{uri}"
      }
   }
}

Webhook Authentication

Webhooks must be configured with an authentication mode. Options are:

  • Custom HTTP Header: Webhook subscriber can configure a header Name and Value for a custom HTTP Header to be included in each webhook call back, e.g. X-PartnerName-API-Key: cee7ef7d-e6ee-4b83-bc60-3a5d5c5c40fe
  • OAuth 2.0 Authorization: Webhook subscriber can configure OAuth details. HICAPS will obtain an access token using the client_credentials flow and include it in the Authorization header as a Bearer token. The configuration options are:
    • OAuth 2.0 Idp Authorize endpoint
    • Client Id
    • Client Secret
    • Scope (optional)

Asynchronous Webhook Handlers

When handling a webhook, the Program webhook handler should handle the request asynchronously.

This means responding very quickly with a success status code (202 Accepted is preferred), and then calling back to the relevant nominated HICAPS URI when the Program is ready to effect the next step in the workflow (e.g. approve a claim).

The style ensures that in the event of processing delays within the program, HICAPS and networking resources are not ‘held open’ for the duration of the delay. It encourages the use of internal queueing mechanisms to ensure robust, reliable & scalable handling of requests even when under load.

Webhook Response Codes

The webhook handler may respond with one of the following HTTP Status Codes. HICAPS actions for each status code are as below.

Status Code HICAPS Action
200 OK
  • Ignore response body
  • Assume the request has been received
  • Wait for callback
202 Accepted (Preferred)
  • Ignore response body
  • Assume the request has been received
  • Wait for callback
4xx Client Error
  • Abandon the webhook
  • Notify HICAPS Support Staff to investigate
5xx Server Error
  • Timeout has occurred.
  • Retry the webhook (see retry policy below)
  • If all retries fail, notify HICAPS Support staff

Webhook Error Handling

If a webhook is delivered to your API handler and you return a 202 Accepted to HICAPS, but then fails to reach your back end handler, you can use the lp:webhook-error link relation on any webhook to automatically initiate HICAPS’s Webhook Retry Policy, explained below. To initiate this retry, send an empty POST (with autentication) to the lp:webhook-error link relation which will trigger the retry policy.

Note: the lp:webhook-error link relation may be null if no retry action is possible.

Retry Policy

If a webhook fails to deliver, the retry policy will trigger as described below. In total there will be 24 attempts to deliver a webhook (the initial attempt + 23 retries) and if all webhooks fail this will trigger an alert to HICAPS support staff for investigation.

All 24 webhook delivery attempts will occur over a ~5.5 minute period, with half the retries delivered within the first ~40 seconds to cover intermittent failures with the receiver. The formula used for each retry is [(number of webhooks already sent)2 x 0.08] where 0.08 represents an 80ms delay.

Each retry will have the same value in the webhook id field. Due to the use of retries, it is strongly recommended that the webhook id field is used to prevent duplicate handling, particularly in the case where HICAPS is retrying due to a timeout, but internal program systems have successfully handled the webhook.

Webhook Delay (s) Time (s)
1 0 0
2 0.08 0.08
3 0.32 0.4
4 0.72 1.12
5 1.25 2.4
6 2 4.4
23 38.72 303.6
24 42.32 345.92

API Resources

This section below details out all the Program API endpoints and the various functionality of each.

Base URIs

Unless stated otherwise, all URIs in the sections below are relative to these base URIs:

Environment URI Description
Sandbox https://api.programs.sandbox.lanternpay.com This is a pre-production environment you can use for testing.
Production https://api.programs.lanternpay.com This is the production environment.

Root

The root resource is the starting point for all API operations when using HATEAOS hypermedia to navigate the API. The first step is to obtain a OAuth access token. This resource can also be used to ensure the Program API is online.

Get the API Root

GET /

The root resource. No credentials, path, query or body parameters are required for this request.

Example Get Root Response

{
    "_links": {
        "self": {
            "href": "https://api.programs.lanternpay.com"
        },
        "lp:oauth-issuer": {
            "href": "https://www.lanternpay.com/ui/iam/identity/oauth"
        },
        "lp:oauth-token": {
            "href": "https://www.lanternpay.com/ui/iam/identity/oauth/connect/token"
        },
        "curies": {
            "name": "lp",
            "href": "https://docs.lanternpay.com/reference#{rel}",
            "templated": true
        }
    }
}

Invoices

An invoice is a representation of the invoice data submitted by a biller. The invoice contains a collection of claims, which represent the line items on the invoice. When the invoice is submitted by the biller, the onInvoiceSubmitted webhook is sent to the program and includes a link to the unique lp:invoice-status-updated URI to POST the adjudications for the claims.

A single response message can contain the result for multiple claims. That is, the Program may respond to all claims in one response, or over multiple responses.

Invoice Submitted

WEBHOOK {onInvoiceSubmitted}

Path Parameters

Field Format Required? Description
onInvoiceSubmitted URI Mandatory The URI you provided for the onInvoiceSubmitted event.

Webhook Body Parameters

Field Description
id A unique ID per event.
created The date and time in Unix Epoch Time of the event.
data Schema follows the structure of an Invoice, as defined below
type claiming.invoice.submitted
_links lp:invoice-status-updated defines the URI to POST the adjudication response(s) to, see below.
lp:webhook-error defines the URI to POST in case the webhook needs to be retried by HICAPS.
Note: this value can be null if no retry is possible.

Invoice Parameters

An invoice is a request for payment and includes an array of individual claims. Mandatory fields will be sent for all Programs and conditional fields are sent depending on Program requirements.

Field Format Required? Description
invoiceId UUID Mandatory HICAPS’s reference for the Invoice.
sourceChannel string Mandatory The channel the invoice was received from.
Values include: bulkimport, web, app, pms.
program string Mandatory Short name of the target program.
See the list of Program codes here.
responsePriority string Mandatory Sets expected SLA for response as appropriate to the source channel.
Values include: stat (immediately/real time), normal (with best effort), deferred (later, when possible).
created dateTime
YYYY-MM-DDTHH:mm:ss.SSS±HH:mm
Mandatory Date and time of creation of this entity by the Provider in their system.
invoiceNumber string Conditional Biller’s identifier for the original invoice.
invoiceDate dateTime
YYYY-MM-DD
Conditional Date of original invoice
biller Biller Conditional Information about the biller sending the invoice.
member Member Conditional The entity who the claim is for.
invoiceCustomFields InvoiceCustomFields Conditional Other invoice-level fields associated with this invoice, as required by the program.
claims An Array of Claims Mandatory List of claims (invoice line items).

Biller Parameters

Additional biller parameters will be defined here as required.

Field Format Required? Description
billerId UUID Mandatory HICAPS’s reference for the Biller sending the invoice.
name String Mandatory The name of the biller.
abn 11 digits Mandatory The ABN of the biller.
address Biller Address Mandatory The address of the biller.

Biller Address Parameters

Field Format Required? Description
lines List of 2 Strings Mandatory Line 1 and Line 2 of the street address.
city String Mandatory The city/suburb of the biller.
postcode String Mandatory The postcode of the biller. E.g. 2043
state String Mandatory The state of the biller. E.g. NSW, VIC, etc.
country String Mandatory The country of the biller.

Member Parameters

Field Format Required? Description
memberNumber string Mandatory Member’s identifier, as issued by the Program.
givenName string Conditional The member’s first name.
familyName string Conditional The member’s last name.
birthDate date
YYYY-MM-DD
Conditional The members date of birth.
gender string Conditional Values include: male, female and unspecified.
email string Conditional The email address of the member.
memberCustomFields MemberCustomFields Conditional Other fields associated with this member, as required by the Program

MemberCustomFields Parameters

The memberCustomFields parameters depend on the program. As disciplines are identified requiring additional specific fields, they will be defined here.

Field Format Required? Description
personIdentifier string Conditional This is the individual identifier of the person making the claim (for the whole invoice), as shown on the membership card.
For example, if the person is listed as the second name on the card, then use "02" as the string value.

InvoiceCustomFields Parameters

The invoiceCustomFields parameters depend on the program. As programs or disciplines are identified requiring additoinal specific fields, they will be defined here.

Field Format Required? Description
medicare Medicare Conditional These fields are required for some Medicare claims.
referral Medicare Referral Conditional These fields are required for some Medicare claims.
medicareDva Medicare DVA Conditional These fields are required for Medicare DVA claims.
ndis NDIS Conditional These fields are required for customers who have access to the NDIS Payee module
wcq WCQ Conditional These fields are required for WorkCover QLD claims

Medicare Invoice Parameters

Field Format Required? Description
payeeProviderNumber string Conditional The provider number of the payee provider, if different from the servicing provider.

Medicare Referral Parameters

Referral information is required for some Medicare claims.
If a referral is required then the below mandatory marked fields are required to be populated.

Field Format Required? Description
issueDate date
YYYY-MM-DD
Mandatory The referral issue date as a string.
overrideCode string Conditional Used when referral services were provided without a referral. Valid values are L (lost), E (emergency), H (hospital), N (not required), R (remote exemption).
periodType string Mandatory The type of referral:
S = Standard (12 months from a GP and 3 months from a Specialist)
N = Non-standard
I = Indefinite
period string Conditional Value represents number of months, e.g. "7" for seven months.
Required only if periodType is "N"
referralProvider Medicare Referral Provider Mandatory Provider object contains information about the referring provider.

Medicare Referral Provider Parameters

Field Format Required? Description
providerNumber string Mandatory The referring provider’s Medicare Provider Number
providerType string Mandatory Valid values include:
G General Practitioner
S Specialist (e.g. Physiotherapist)

Medicare DVA Parameters

Field Format Required? Description
disability Disability Mandatory Required for Medicare DVA claims.

Medicare DVA Disability Parameters

Field Format Required? Description
description string Mandatory The member’s White Card condition description. Note this must exactly match the value that Medicare holds for this member.
Note: description must be set to null if no White Card description is provided.
isRelated boolean Mandatory Must be set to false by default, or set to true to indicate if the treatment being claimed is related to the member’s White Card condition description.

NDIS Invoice Parameters

This format is used to make a corresponding payment to payee on the same day that NDIS funds are received by the provider.

Field Format Required? Description
payeeInvoice boolean Conditional When set to true and the Provider has access to the Payee module, then a payment will be attempted for each successful claim.
payee NDIS payee Conditional Required when payeeInvoice is set to true. Contains the payee information.

NDIS Payee Invoice Parameters

Field Format Required? Description
name string Conditional The name of the Provider. Required when payeeInvoice set to true.
email string Conditional The email address of the payee, this controls where the remittance will be sent. Required when payeeInvoice set to true.
reference string Optional The customers reference for the payee.
bsb 6 digits Conditional The BSB number of the payee bank account. Required when payeeInvoice set to true.
accountNumber 1 to 9 digits Conditional The account number of the payee bank account. Required when payeeInvoice set to true.
accountHolder string Conditional The account name of the payee bank account. Required when payeeInvoice set to true.

WCQ Invoice Parameters

Field Format Required? Description
billerAccountNumber string Mandatory The account number issued by WCQ for this biller.

Claims Parameters

Field Format Required? Description
claimId UUID Mandatory HICAPS’s reference for the Claim. This field will always be populated.
sequence string Conditional Invoice line item identifier from Biller’s system (PMS or bulk upload line)
provider Provider Conditional Details of the person who performed the service.
itemPublisher string Conditional Entity that has responsibility for defining the item code below. Resolves the situation where the same item code occurs in different publisher lists
itemCode string Mandatory The unique identifier for the service or goods
itemCustomFields ItemCustomFields Conditional Additional service details, as required for some programs.
patient Patient Conditional If the patient receiving service is different to the member/claimant
serviceDate date
YYYY-MM-DD
Conditional The date that the service was performed in date format. Required if serviceDateTime or servicePeriod is not provided.
serviceDateTime dateTime
YYYY-MM-DDTHH:mm:ss.sss±HH:mm
Conditional The date and time that the service was performed in dateTime format. Required if serviceDate or servicePeriod is not provided.
servicePeriod Period Conditional The start and end date and time that the service was performed in dateTime format. Required if serviceDate or serviceDateTime is not provided.
location Location Conditional Location where the service occurred
consentReceived boolean Conditional Client/patient consent has been granted
consentAuthority string Conditional The party who has the consent record
quantity decimal (4 dp) Conditional Note: the unit of measure is defined by the Program for each item. 4 dp is required to allow Billers to allow quantity * price to equal a specific total.
unitPrice decimal (4 dp) Conditional 4 dp is required to allow Billers to allow quantity * price to equal a specific total.
taxCode string Conditional Values include: GST, FRE
description string Conditional Description of the item or service
contractNumber string Conditional The contract that this claim is claimed against.
contractLineItemNumber string Conditional The contract line item that this claim is claimed against.

Provider Parameters

A Provider can be either an organization, such as a sports complex, gym or pharmacy, or a person, such as a physiotherapist, doctor, or dentist. Different data needs to be captured for each type of Provider.

Field Format Required? Description
person Person Conditional The details of a person Provider. Required when the Provider is a person.
organization Organization Conditional The details of an organization Provider. Required when the Provider is an organization.
registrations Registrations Conditional Any registrations that the provider has.
contactPoint ContactPoint Conditional Contact options for this provider and their respective numbers/values.
discipline string Conditional The provider’s discipline. Also known as modality or provider type. The discipline must be in accord with the respective claim in case a provider is qualified in multiple disciplines.
See the list of possible provider disciplines here

Person Parameters

Field Format Required? Description
givenName string Conditional The given name of the Provider.
familyName string Conditional The family name of the Provider.

Organization Parameters

Field Format Required? Description
facilityName string Mandatory The name of the organisation facility that provided the service. Eg. the name of a gym or sports complex.

Registrations Parameters

Field Format Required? Description
ahpraRegistrationNumber string Conditional The AHPRA number of the provider.
medicareProviderNumber string Conditional The Medicare number of the provider.
medibankProviderNumber string Conditional The Medibank number of the provider.
worksafevicProviderNumber string Conditional The Worksafe Victoria number of the provider.
pbsPharmacyApprovalNumber string Conditional The PBS Pharmacy Approval number of the provider.

ContactPoint Parameters

Field Format Required? Description
phone string Conditional The provider’s phone number.
email string Conditional The provider’s email address.
mobile string Conditional The provider’s mobile number.
other string Conditional Any other contact information for the provider.

Provider Disciplines

Below are a list of possible values for provider.discipline. Also known as modality or provider type.

Click to expand

  • Aboriginal Health Worker
  • Accommodation
  • Acupuncturist
  • Addiction Medicine
  • Advanced Dental Technician
  • Ambulance
  • Anaesthetics
  • Audiologist
  • Audiology (Medicare) - Company
  • Cardiologist
  • Chiropodist/Podiatrist
  • Chiropractor
  • Clinical Genetics
  • Clinical Psychologist
  • Complimentary Therapist
  • Consultant/Phys General Med
  • Counselling
  • Dental Hygienist
  • Dental Prosthetist
  • Dental Therapist
  • Dentist
  • Dermatology
  • Diabetes Educator
  • Dietitian/Nutritionist
  • Doctor
  • Domestic Service Provider
  • Driving Instructor
  • Emergency Medicine
  • Endocrinology
  • Endodontist
  • Equipment Supplier
  • Exercise Physiology
  • Gastroenterologist
  • General Surgeon
  • Geriatrics Physician
  • Haematologist
  • Immunology
  • Infectious Diseases Consultant
  • Interpreting Service
  • Lifestyle Retailer
  • Massage Therapy
  • Medical Non-GP/Specialist
  • Mental Health Nurse
  • Midwife
  • Myotherapy
  • Naturopaths
  • Neurosurgery
  • Nuclear Medicine
  • Nurse
  • Nurse Practitioner
  • Obstetrics & Gynaecology
  • Occupational Therapist
  • Oncologist
  • Ophthalmology
  • Optical Dispensary
  • Optical Dispenser (Company)
  • Optometrist
  • Oral/Maxillofacial Surgeon
  • Orthodontist
  • Orthopaedic Surgery
  • Orthoptist
  • Osteopath
  • Otorhinolaryngology (ENT)
  • Paediatric Dentist
  • Paediatric Medicine
  • Pain Medicine
  • Palliative Medicine
  • Pathologist
  • Periodontist
  • Pharmacy
  • Physical Educator
  • Physiotherapist
  • Plastic & Reconstructive Surgery
  • Podiatrist
  • Prosthodontist
  • Psychiatry
  • Psychologist
  • Radiologist
  • Rehabilitation Physician
  • Renal Medicine
  • Rheumatologist
  • Sleep Physician
  • Social Worker
  • Speech Therapist
  • Sports Complex/Gym
  • Sports Physician
  • Transport
  • Urologist
  • Vascular Surgeon
  • Vocational Provider

ItemCustomFields Parameters

The itemCustomField parameters depend on the claim’s discipline. As more disciplines are identified requiring additional specific fields, they will be defined here.

Field Format Required Description
ndis NDIS Conditional This field is conditional for NDIS API Managed claims.
medicare Medicare Conditional This field is conditional for Medicare claims.
generalMedical General Medical Conditional This field is conditional for general medical claims.
pharmacy Pharmacy Conditional This field is conditional for pharmacy claims.
ambulance Ambulance Conditional This field is conditional for ambulance claims.
pathologist Pathologist Conditional This field is conditional for pathology claims.
radiologist Radiologist Conditional This field is conditional for radiology claims.
dental Dental Conditional This field is conditional for dental claims.

NDIS Parameters

Field Format Required? Description
serviceBookingNumber integer Conditional This field is required for API claims. Maximum 10 digits.
providerAbn 11 digits ABN Conditional This field is mandatory when claiming against a plan managed service booking and the payee possesses a valid ABN. If the payee does not possess a valid ABN then a valid NDIA exemption reason mnemonic should be included in the exemptionReason field. If the ABN is omitted or the ABN does not conform to the defined ABN format, then the claim will not be accepted.
exemptionReason Valid NDIS exemption mnemonic Conditional This field must be provided when claiming against a plan managed service booking and an ABN is applicable or available for a provider. A valid NDIA exemption reason mnemonic must be used when this condition is met.
claimType string
(4 chars)
Conditional This field should be null (or omitted) for standard claim types.
For other claim types, valid values are:
REPW (NDIA Required Report)
TRAN (Provider Travel)
NF2F (Non-Face-to-Face Service)
THLT (Telehealth Support)
IRSS (Irregular SIL Support)
CANC (Cancellation)
If CANC is the provided value then a cancellation reason (see below) must be provided.
Note: CANC is not a cancellation of an invoice but is a specific NDIS claim type.
cancellationReason string
(4 chars)
Conditional If claim type (above) is submitted with CANC then a cancellation reason must be provided.
Valid values are:
NSDH (No show due to health reason)
NSDF (No show due to family issue)
NSDT (No show due to unavailability or transport)
NSDO (Other).

NDIS ABN Values

The NDIS requires that a valid ABN be provided when claiming against a plan managed service booking and when the payee/service provider holds an ABN. If the provider/payee does not hold a valid ABN, then an ABN exemption reason will need to be supplied. The below table lists the NDIS’s accepted exemption reason codes:

Value Description
11 digit ABN A valid ABN for the payee. Note that this must meet the defined ABN format, if the value provided does not meet this check, then the invoice will default to REIMB
REIMB Participant Reimbursement – You are declaring that this payment request is a reimbursement to a participant for services and goods purchased in accordance with the funded supports outlined in the participants NDIS plan. By selecting this, you must be able to provide the tax invoice and other relevant documentation should the NDIA request it.
EXCLS ATO Excluded Supply – You are declaring that this payment request is being made to a supplier in connection with a supply that is excluded from the withholding tax rules. By selecting this, you are declaring that the supplier has provided you with the completed ATO form ‘Statement by Supplier’ and you are able to provide the completed form on request.

Medicare Claim Parameters

Field Format Required? Description
distance integer Conditional The distance in km, e.g. 15
Note: itemCode must be set to "KM" if distance is used.
Additionally, distance cannot be used if location.type=R
duplicateServiceOverride boolean Conditional Set to true if practitioner attended patient on more than one occasion on same day.
afterCareOverride boolean Conditional Set to true to indicate that a service is not normal aftercare (i.e. treated for an unrelated condition or for complications form the operation)

General Medical Parameters

Field Format Required? Description
numberOfPatients integer Conditional The number of patients associated with the claim.

Pharmacy Parameters

Field Format Required? Description
scriptNumber string Conditional The script number of the item.
prescribingDoctorNumber string Conditional The doctor number of the doctor who prescribed the item, as stated on the script.
prescribingDoctorName string Conditional The name of the doctor who prescribed the item, as stated on the script.
itemsDispensed string Conditional The number of individual items (e.g. pills) dispensed if a part-pack.
isScriptPrivate boolean Conditional A true/false identifier as to whether the script is a private script.

Ambulance Parameters

Field Format Required? Description
pickUpDateTime dateTime
YYYY-MM-DDTHH:mm:ss.sss±HH:mm
Optional The start date and time of the ambulance journey
pickUpAddressLine1 string Optional The first line of the pick up address
pickUpAddressLine2 string Optional The second line of the pick up address
pickUpCity string Optional The city/suburb of the pick up location
pickUpPostalCode string Optional The post code of the pick up location
pickUpState string Optional The state of the pick up location, e.g. "NSW", "VIC"
dropOffDateTime dateTime
YYYY-MM-DDTHH:mm:ss.sss±HH:mm
Optional The end date and time of the ambulance journey
dropOffAddressLine1 string Optional The first line of the drop off address
dropOffAddressLine2 string Optional The second line of the drop off address
dropOffCity string Optional The city/suburb of the drop off location
dropOffPostalCode string Optional The post code of the drop off location
dropOffState string Optional The state of the drop off location, e.g. "NSW", "VIC"
kms string Optional The distance travelled in kilometres

Pathologist Parameters

Field Format Required? Description
prescribingDoctorNumber string Conditional The doctor number of the doctor who prescribed/referred the service.
prescribingDoctorName string Conditional The name of the doctor who prescribed/referred the service.

Radiologist Parameters

Field Format Required? Description
prescribingDoctorNumber string Conditional The doctor number of the doctor who prescribed/referred the service.
prescribingDoctorName string Conditional The name of the doctor who prescribed/referred the service.

Dental Parameters

Field Format Required? Description
jaw string Conditional Identifies if the dental service relates to the upper or lower jaw. Valid values: upper or lower.
numberOfTeeth integer Conditional Number of teeth.
toothNumber integer Conditional Identifies the tooth number that relates to the dental service provided.

Patient Parameters

The patient parameters at the claim level are for all program claims except medicare claims. For medicare, use the patient parameters are the invoice level.

A patient may be the same or different to the member making the claim. For example the patient may be a child or dependant of a member.

Field Format Required? Description
memberNumber string Mandatory Member’s identifier, as issued by the Program.
givenName string Conditional The patient’s first name.
familyName string Conditional The patient’s last name.
birthDate date
YYYY-MM-DD
Conditional The patient’s date of birth.
gender string Conditional Values include: male, female and unspecified.
patientCustomFields PatientCustomFields Conditional Other fields associated with this patient, as required by the Program.

PatientCustomFields Parameters

The patient parameters at the claim level are for all program claims except medicare claims. For medicare, use the patient parameters are the invoice level.

As programs are identified requiring additional specific fields, they will be defined here.

Field Format Required? Description
personIdentifier string Conditional This is the individual identifier of the person making the claim (for an individual claim line item), as shown on the membership card.
For example, if the person is listed as the first (or only) name on the card, then use "1" as the string value.

Period Parameters

Field Format Required? Description
start dateTime
YYYY-MM-DDTHH:mm:ss.SSS±HH:mm
Mandatory Start date time of the service.
end dateTime
YYYY-MM-DDTHH:mm:ss.SSS±HH:mm
Mandatory End date time of the service.

Location Parameters

Field Format Required? Description
address Address Conditional The address where the service occurred.
position Position Conditional The GPS position (WGS84) where the service occurred.
type string conditional Required for Medicare claims. Valid values are:
H Hospital
V Home Visit
R Rooms - Note: itemCustomFields.medicare.distance cannot be used with Location type=R
N Residential Care Facility
C Community Health Centres

Address Parameters

Field Format Required? Description
lines Array of strings Mandatory Each line of the street address is a separate string.
city string Mandatory The city that the service occurred in.
postalCode string Mandatory The post code that the service occurred in.
state string Mandatory The state that the service occurred in.
country string Conditional The country that the service occurred in.

Position Parameters

Field Format Required? Description
longitude decimal Mandatory WGS84 longitude
latitude decimal Mandatory WGS84 latitude
altitude decimal Mandatory WGS84 altitude

Example Invoice Submitted Webhook

{
    "id": "8ad735a2-21a0-481a-9174-205817e95110",
    "created": 1565140165,
    "data": {
        "invoiceId": "9a15ad10-dbf0-4ab6-83f1-e42019f188b5",
        "sourceChannel": "app",
        "program": "mpl",
        "responsePriority": "normal",
        "biller": {
            "billerId": "de960e0a-5a3b-47e7-8cde-11f6d3b62b60",
            "name": "My Biller Pty Ltd",
            "abn": "27114508771",
            "address": {
                "lines": [
                    "Some street name",
                    "Second line"
                ],
                "city": "Manly",
                "postalCode": "2095",
                "state": "NSW",
                "country": "Australia"
            }
        },
        "member": {
            "memberNumber": "789456123",
            "program": "mpl",
            "givenName": "Spongebob",
            "familyName": "Squarepants",
            "birthDate": "1990-04-01",
            "gender": "female"
        },
        "created": "2019-11-15T01:09:23.633+10:00",
        "invoiceDate": "2019-11-01",
        "invoiceNumber": "INV-911",
        "claims": [
            {
                "claimId": "7329d4a5-a15d-4db0-a831-da2e6bbba425",
                "provider": {
                    "organization": {
                        "facilityName": "Amcal Bourke Street"
                    },
                    "registrations": {
                        "medibankProviderNumber": "808000"
                    },
                    "contactPoint": {
                        "phone": "097591423"
                    },
                    "discipline": "pharmacy"
                },
                "itemPublisher": "mims",
                "itemCode": "10|1|1",
                "itemCustomFields": {
                    "pharmacy": {
                        "scriptNumber": "123123",
                        "prescribingDoctorName": "Squidward Tentacles",
                        "dispensingPharmacistName": "Patrick Star"
                    }
                },
                "serviceDateTime": "2019-08-07T00:00.000+10:00",
                "quantity": 1,
                "unitPrice": 55.63,
                "taxCode": "GST",
                "description": "LonquexSolution for injection6 mg/0.6 mL [1]"
            }
        ]
    },
    "type": "claiming.invoice.submitted",
    "_links": {
        "lp:invoice-status-updated": {
            "href": "https://lanternpay.com/sample/invoices/9a15ad10-dbf0-4ab6-83f1-e42019f188b5/res"
        },
        "lp:webhook-error": {
            "href": "https://lanternpay.com/sample/webhook/8ad735a2-21a0-481a-9174-205817e95110"
        }
    }
}

Invoice Cancellation Requested

WEBHOOK {onInvoiceCancellationRequested}

A Biller can request the cancellation of an invoice at any time. HICAPS will forward this cancellation request to the Program for their decision.

The Program may accept and complete the cancellation of an invoice as a whole, partially or not accept the cancellation at all.

HICAPS expects the Program to communicate their decision by sending an updated POST Invoice Status Updated. i.e it is in the Program’s hands to move each claim’s state from cancelPending either back to approved (or which ever state the claim had before) or to cancelled.

Out of Sequence Messages

There is a chance that a Program will receive a cancellation request for an invoice they have not seen yet. The recommended way of handling this scenario is to respond to the cancellation request by updating the invoice status to cancelled then store the invoiceId. When the same invoice comes as an Invoice Submitted Webhook, the Program can disregard the webhook.

Path Parameters

Field Format Required? Description
onInvoiceCancellationRequested URI Mandatory The URI you provided for the onInvoiceCancellation event.

Webhook Body Parameters

Field Description
id A unique ID per event.
created The date and time in Unix Epoch Time of the event.
data Schema follows the structure of a CancellationRequest, as defined below.
type claiming.invoice.cancellationRequested
_links lp:invoice-status-updated defines the URI to POST the response to the cancellation request.
lp:webhook-error defines the URI to POST in case the webhook needs to be retried by HICAPS
Note: this value can be null if no retry is possible.

CancellationRequest Parameters

Field Format Required? Description
program string Mandatory Short name of the target program.
See the list of Program codes here.
invoiceId UUID Mandatory HICAPS’s reference for the Invoice to be cancelled.
programInvoiceId String Conditional If the program supplied their invoice ID for this invoice previously, this will be populated here to aid identification.
reason string Conditional A reason for the invoice cancellation.

Example Claim Cancellation Webhook

{
    "id": "6c58efc3-9658-4e90-9e58-c3b2d7f74920",
    "created": 1565676298,
    "data": {
        "program": "mpl",
        "invoiceId": "e23cb7e3-93c6-4e0b-8229-c95a0d0447c3",
        "programInvoiceId": "IC2342348_90",
        "reason" : "The invoice has been submitted by mistake."
    },
    "type": "claiming.invoice.cancellationRequested",
    "_links": {
        "lp:invoice-status-updated": {
            "href": "https://api.lanternpay.com/sample/invoices/08c9c003-3709-4475-85ce-98b7b318c2da/response"
        },
        "lp:webhook-error": {
            "href": "https://lanternpay.com/sample/webhook/8ad735a2-21a0-481a-9174-205817e95110"
        }
    }
}

Invoice Status Updated

POST {invoiceResponse}

Ideally, the Program should respond to the invoice webhook with a single response message containing a result for all claims in the invoice. However, the Program may respond over multiple responses, if for example, some of the claims have an immediate outcome while others will require longer to adjudicate. Note: The Program should consider the responsePriority from the invoice when deciding whether a delayed response for some claims is appropriate.

A program can choose to reject, cancel or set to pending an invoice at the invoice level if they choose, rather than setting these statuses for each claim individually. However, if the program is approving the invoice then each claim state and benefit must be set individually.

The outcome of each claim (claimStatuses) must contain a funded amount (benefit) and define a state (such as approved or rejected)

The Program is then encouraged to include additional detail to assist the Biller to understand the outcome of the claim, which may include:

  • statusTitle and statusDescription: can be used to give the biller a more specific description of the state of the claim, if there are multiple sub-states for the claim (see States, Statuses & Actions)
  • adjudications: these explain how the Program came to the adjudication decision
  • invalidParams: a listing of any issues with specific fields in a claim (at both the invoice-level and claim-level) that contributed to the outcome (e.g. an unknown value causing a rejection), so the Biller can easily find and rectify them for the next claim

Path Parameters

Field Description
invoiceResponse The lp:invoice-status-updated link relation in the onInvoiceSubmitted webhook.

Body Parameters

Field Format Required? Description
programInvoiceId string Conditional Sets the Program’s reference for the invoice, which may be used in subsequent API calls (such as invoice cancellation).
actions Array of Actions Conditional An optional list of actions the biller can take if there are issues with the claim.
state enum Conditional A program may reject, cancel or set to pending an entire invoice, rather than setting the individual claim statuses. If the program is approving some or all of the claims then this invoice-level state cannot be set and each individual claim must be set via the claimStatuses array, below.
Accepted values for invoice-level state are: rejected, cancelled, cancelRejected, pending or cancelPending
Note: the API message is invalid if both state at the invoice level, and claimStatuses at the claim level are present.
claimStatuses Array of ClaimStatuses Conditional An array of responses to the claims (line items) on the invoice.
invalidParams Array of Invalid Parameters Conditional An array of fields and their associated errors, at the invoice level. Where specified, this data may be used by the software submitting the Biller’s invoice to highlight particular fields within claims which are leading to a rejection or lesser funding result.

Actions Parameters

The program may choose to respond to a claim submission with a list of one or more actions that the Provider can take if they are required to do something before the claim can be processed further by the Program. For example, a program may require a provider to provide additional detail on the service provided before the claim can be adjudicated, or they may require the provider to complete onboarding before the claim is processed and a payment made.

Field Format Required? Description
title string Conditional A short title for the action which may display as a tooltip.
description string Conditional A contextual description of the action required to be taken by the provider.
href URI Conditional A link, if applicable, the biller can follow for more infomration or to complete the action.
class string Conditional The type of action this is, for example info or action

ClaimStatuses Parameters

Field Format Required? Description
claimId UUID Mandatory Found in the claim object in the data payload of the Invoice Submitted Event webhook
programClaimId string Conditional Sets the Program’s reference for the claim, which may be used in subsequent API calls (such as updating payment information).
benefit decimal 2dp Conditional The amount to be paid by the Program for this claim. If the Program is only providing a status field update for the claim, then this field may be empty.
adjudications Array of Adjudications Conditional The adjudication provides additional detail on the various components of the funding decision. The Adjudication information does not have any impact on the amount paid by the Program (i.e. benefit).
state enum Conditional Values include provisionallyApproved, approved, rejected, cancelled. These values are described in the Claim State table.
statusTitle string Conditional Displayed to the biller as a custom status of the claim set by the Program. Normally not required. Only required where the standard “state” would not effectively communicate the state to the Biller. See States, Statuses & Actions. Maximum of 20 chars.
statusDescription string Conditional Displayed to the biller as the description of the status of the claim. The statusDescription will only be provided if a custom statusTitle has been returned.
invalidParams Array of Invalid Parameters Conditional An array of fields and their associated errors, at the claim level. Where specified, this data may be used by the software submitting the Biller’s invoice to highlight particular fields within claims which are leading to a rejection or lesser funding result.

Adjudications

The Adjudication provides the Biller with additional information about the breakdown of the funding result. The various Adjudications can be displayed on the receipt/screen to explain to the client/patient how the result was attained. The Adjudication information does not have any impact on the amount paid by the Program (i.e. benefit).

Field Format Required? Description
reason string Conditional Provides a text description of the adjudication result.
amount decimal 2dp Conditional Used where the reason refers to a monetary amount. eg. “20.00”.
value string Conditional Used where the reason refers to a non-monetary amount. For example “70%”

Example Invoice Status Updated Request

{
    "programInvoiceId" : "CLM-123213",
    "claimStatuses": [
        {
            "claimId": "ef5bc5d2-943e-473c-bfc4-dab2e252a000",
            "programClaimId":"AA-1231231",
            "benefit": 690,
			"adjudications": [
                {
                    "reason": "Policy limit for Physiotherapy reached",
                    "amount": 590
                },
                {
                    "reason": "Client is eligible to receive a Bonus to cover the claim amount",
                    "amount": 100
                }
            ],
            "state": "approved"
        },
        {
            "claimId": "ac2a7251-149e-4e5a-b526-bbc9e256723b",
            "programClaimId":"AA-3453434",
            "benefit": 0,
            "state": "rejected",
			"statusTitle": "InvCombo",
            "statusDescription": "ItemCode 12345 is not allowed in combination with itemCode 4567"
        },
        {
            "claimId": "68e1a679-a455-4726-b52d-d467c7f2d1f5",
            "programClaimId":"AA-897978",
            "benefit": 0,
            "state": "rejected",
			"statusTitle": "Invalid",
            "invalidParams": [
                {
                    "name": "itemCode",
                    "reason": "Item 123456 is unknown"
                },
                {
                    "name": "location",
                    "reason": "A location is required for this claim"
                }
            ]
        }
    ]
}

Predeterminations

The Predetermination process is used to request an expected funding result for an Invoice. The Predetermination may not be subsequently honoured by the Program - the result of the Submit is the final and true result. It is expected that the rules applied by a Program for calculating the result of a Predetermination are the same as those which will apply on the Submit. The Predetermination is used for information purposes only, and does not change the State of the claim.

The Predetermination is sent as an Invoice (containing a collection of Claims), but the result for each Claim is processed and returned independently. The Predetermination process may be run several times before a Submit, the most recently received Predetermination response will be displayed to the Biller.

If Predetermination is not supported by a Program it may be configured to be bypassed, in which case the Biller will not be given any indication of the expected result prior to submission.

The data structure for a Predetermination is the same as an Invoice.

Predetermination Submitted

WEBHOOK {onPredeterminationSubmitted}

Path Parameters

Field Format Required? Description
onPredeterminationSubmitted URI Mandatory The URI you provided for the onPredeterminationSubmitted event.

Webhook Body Parameters

Field Description
id A unique ID per event.
created The date and time in Unix Epoch Time of the event.
data Schema follows the structure of an Invoice.
type claiming.predetermination.submitted
_links lp:predetermination-status-updated defines the URI to POST the predetermination status update(s) to, see below.
lp:webhook-error defines the URI to POST in case the webhook needs to be retried by HICAPS.
Note: this value can be null if no retry is possible.

Example Predetermination Submitted Webhook

{
    "id": "8ad735a2-21a0-481a-9174-205817e95110",
    "created": 1565140165,
    "data": {
        "invoiceId": "9a15ad10-dbf0-4ab6-83f1-e42019f188b5",
        "sourceChannel": "app",
        "program": "mpl",
        "responsePriority": "normal",
        "biller": {
            "billerId": "de960e0a-5a3b-47e7-8cde-11f6d3b62b60"
        },
        "member": {
            "memberNumber": "789456123",
            "program": "mpl",
            "givenName": "Spongebob",
            "familyName": "Squarepants",
            "birthDate": "1990-04-01",
            "gender": "female"
        },
        "created": "2019-11-15T01:09:23.633+10:00",
        "invoiceDate": "2019-11-01",
        "invoiceNumber": "INV-911",
        "claims": [
            {
                "claimId": "7329d4a5-a15d-4db0-a831-da2e6bbba425",
                "provider": {
                    "organization": {
                        "facilityName": "Amcal Bourke Street"
                    },
                    "registrations": {
                        "medibankProviderNumber": "808000"
                    },
                    "contactPoint": {
                        "phone": "097591423"
                    },
                    "discipline": "pharmacy"
                },
                "itemPublisher": "mims",
                "itemCode": "10|1|1",
                "itemCustomFields": {
                    "pharmacy": {
                        "scriptNumber": "123123",
                        "prescribingDoctorName": "Squidward Tentacles",
                        "dispensingPharmacistName": "Patrick Star"
                    }
                },
                "serviceDateTime": "2019-08-07T00:00.000+10:00",
                "quantity": 1,
                "unitPrice": 55.63,
                "taxCode": "GST",
                "description": "LonquexSolution for injection6 mg/0.6 mL [1]"
            }
        ]
    },
    "type": "claiming.predetermination.submitted",
    "_links": {
        "lp:predetermination-status-updated": {
            "href": "https://lanternpay.com/sample/invoices/9a15ad10-dbf0-4ab6-83f1-e42019f188b5/predet"
        },
        "lp:webhook-error": {
            "href": "https://lanternpay.com/sample/webhook/8ad735a2-21a0-481a-9174-205817e95110"
        }
    }
}

Predetermination Status Updated

POST {predeterminationResponse}

Path Parameters

Field Description
predeterminationResponse The lp:predetermination-status-updated link relation in the onPredeterminationSubmitted webhook.

Body Parameters

Field Format Required? Description
invalidParams Array of Invalid Parameters Conditional An array of fields and their associated errors, at the predetermination level. Where specified, this data may be used by the software submitting the Biller’s invoice to highlight particular fields within claims which are leading to a rejection or lesser funding result.
claimStatuses Array of ClaimStatuses Mandatory

Example Predetermination Response

{
    "claimStatuses": [
        {
            "claimId": "ef5bc5d2-943e-473c-bfc4-dab2e252a000",
            "benefit": 690,
            "adjudications": [
                {
                    "reason": "Policy limit for Physiotherapy reached",
                    "amount": 690
                }
            ],
            "state": "rejected",
            "statusDescription": "ItemCode 12345 is unknown. A location is required for this claim.",
            "invalidParams": [
                {
                    "name": "itemCode",
                    "reason": "Item 123456 is unknown"
                },
                {
                    "name": "location",
                    "reason": "A location is required for this claim"
                }
                ]
        },
        {
            "claimId": "ef5bc5d2-943e-473c-bfc4-dab2e252a123",
            "benefit": 90.05,
            "state": "approved"
        }
    ]
}

Members

A Member is also known as the “client” or “participant” in the Program. Programs have different requirements for identifying a member, which is further covered under Member Validation.

Member Validation Requested

WEBHOOK {onMemberValidationRequested}

To submit a Claim, the Biller must supply a valid Member Number. The Member Validation flow is provided to support two use cases:

  • the Member Number is not known to the Biller, and the Biller needs to look up the Member Number before submission of a Claim
  • the Biller wishes to validate if a Member Number is known to the Scheme prior to attempting to Submit an invoice, rather than have the claims rejected at time of submission

Path Parameters

Field Format Required? Description
onMemberValidation URI Mandatory The URI you provided for the onMemberValidation event.

Webhook Body Parameters

Field Description
type admin.member.check
data Schema follows the structure of a Member, defined below.
_links lp:update-member-state defines the URI to POST the Member State to, see below.
lp:webhook-error defines the URI to POST in case the webhook needs to be retried by HICAPS.
Note: this value can be null if no retry is possible.

Member Parameters

Field Format Required? Description
memberNumber string Mandatory Member’s identifier, as issued by the Program.
program string Mandatory Short name of the target program. See the list of Program codes here.
givenName string Conditional The member’s first name.
familyName string Conditional The member’s last name.
birthDate date
YYYY-MM-DD
Conditional The members date of birth.
gender string Conditional Values include: male, female and unspecified.
email string Conditional The email address of the member.
memberCustomFields MemberCustomFields Conditional Other fields associated with this member, as required by the Program.

MemberCustomFields Parameters

The memberCustomFields parameters depend on the program. As disciplines are identified requiring additional specific fields, they will be defined here.

Example Member Validation Webhook

Example code here

Member Status Updated

POST {memberStatusUpdated}

Set the program’s memberNumber and state (and conditionally statusTitle and statusDescription).

Path Parameters

Field Description
memberStatusUpdated The lp:update-member-state link relation in the onMemberValidationRequested webhook.

Body Parameters

Field Format Required? Description
memberNumber string Mandatory set the Program’s number for this Member
setState enum Conditional Values include: approved, rejected. Updates the state of the Member.
statusTitle string Conditional Describes the Member’s status with this Program
statusDescription string Conditional Describes the reason for the status with this Program

Example Update Member Status

Example code here

Payments

HICAPS will trigger webhooks to inform the program of certain payment related events, defined below.

NOTE: this payments section is currently being updated to support direct debit payment notifications. Please speak with an integration resource regarding this for the latest information.

Payment Scheduled

WEBHOOK {onPaymentScheduled}

The Payment Scheduled webhook alerts the program that a payment instruction has been sent to the bank. Details of the payment are provided in the webhook body, including the bank account details of the biller that was paid. A further breakdown of all invoices and claims linked to this payment can be queried via the lp:payment-invoices link relation.

Path Parameters

Field Format Required? Description
onPaymentScheduled URI Mandatory The URI you provided for the onPaymentScheduled event.

Example Payment Scheduled Webhook

{
    "id": "d76eac52-6b7f-4303-8c70-91ae2f4313f9",
    "created": "2020-10-30T09:10:11.2321413+11:00",
    "data": {
        "remitter": "tac",
        "paymentDate": "2020-04-04",
        "billerId": "d5e6e8f7-bc9c-4a5b-8c60-8e8ffd665e26",
        "paymentId": "55435069-4217-4c8b-8d17-7c7edec69796",
        "paymentReference": "YHL233432424ref",
        "amount": 2322.23,
        "billerBankAccount": {
            "bsb": "123123",
            "accountNumber": "123456789",
            "accountName": "ABC Care"
        }
    },
    "type": "settlement.payment.scheduled",
    "_links": {
        "lp:payment-invoices": {
            "href": "https://api.payments.sandbox.lanternpay.com/payments/55435069-4217-4c8b-8d17-7c7edec69796/invoices"
        },
        "lp_webhook-error": {
            "href": "https://lanternpay.com/sample/webhook/url/8ad735a2-21a0-481a-9174-205817e95110"
        }
    }
}

Payment Failed

WEBHOOK {onPaymentFailed}

The Payment Failed webhook alerts the program that a previous payment has failed and been returned to HICAPS. HICAPS will contact the biller directly to rectify the issue. Once the issue is resolved, a onPaymentScheduled webhook will trigger when the failed payments have been paid.

Path Parameters

Field Format Required? Description
onPaymentFailed URI Mandatory The URI you provided for the onPaymentFailed event.

Example Payment Failed Webhook

{
    "id": "d76eac52-6b7f-4303-8c70-91ae2f4313f9",
    "created": "2020-10-30T09:10:11.2321413+11:00",
    "data": {
        "remitter": "tac",
        "paymentDate": "2020-04-04",
        "billerId": "d5e6e8f7-bc9c-4a5b-8c60-8e8ffd665e26",
        "paymentId": "55435069-4217-4c8b-8d17-7c7edec69796",
        "paymentReference": "YHL233432424ref",
        "amount": 2322.23,
        "billerBankAccount": {
            "bsb": "123123",
            "accountNumber": "123456789",
            "accountName": "ABC Care"
        }
    },
    "type": "settlement.payment.failed",
    "_links": {
        "lp:payment-invoices": {
            "href": "https://api.payments.sandbox.lanternpay.com/payments/55435069-4217-4c8b-8d17-7c7edec69796/invoices"
        },
        "lp_webhook-error": {
            "href": "https://lanternpay.com/sample/webhook/url/8ad735a2-21a0-481a-9174-205817e95110"
        }
    }
}

Payment Invoices

GET /payments/{paymentId}/invoices

This API can be used to retrieve a list of invoices and claims relating to a specific biller payment. The API will respond with a breakdown of an individual Payment, which is made up of invoices, which is made up of claim transactions as they relate to this individual payment.

Note that this API has a different subdomain than the rest of the Program API. This subdomain is api.payments (e.g. https://api.payments.sandbox.lanternpay.com) rather than api.programs (e.g. https://api.programs.sandbox.lanternpay.com) as it’s a service used by multiple HICAPS APIs so you should always use the URI in the lp:payment-invoices link relation of the onPaymentScheduled webhook to build your API request.

Path Parameters

Field Format Required? Description
paymentId UUID Mandatory HICAPS’s unique reference for the payment, provided in the Payment Scheduled or Payment Failed webhook.

Example Payment Invoices Response

{
    "invoices": [
        {
            "invoiceId": "614f61e1-c62c-4d42-b0cf-3bf972030c21",
            "programInvoiceId": "47d6538e-de2b-4877-80cf-f293fbb36d30",
            "claimTransactions": [
                {
                    "claimId": "ea070557-757d-4127-8be6-690cb05b948a",
                    "amount": 234.23
                },
                {
                    "claimId": "54eadf24-aaba-4dbd-8d3b-f15f01c0ad3f",
                    "amount": 34.12
                }
            ]
        },
        {
            "invoiceId": "123ae1db-843e-461c-aab9-7dbaef7c83b6",
            "claims": [
                {
                    "claimId": "32170557-757d-4127-8be6-690cb05b948a",
                    "amount": 14.23
                },
                {
                    "claimId": "222adf24-aaba-4dbd-8d3b-f15f01c0ad3f",
                    "amount": 45.12
                }
            ]
        }
    ]
}

Invoice Payment Held

WEBHOOK {onInvoicePaymentHeld}

The Invoice Payment Held webhook alerts the program that there is an issue preventing HICAPS from making payments to a biller which may result in extra funds remaining in the remitter’s bank account. HICAPS will contact the biller directly to rectify the issue. Once the issue is resolved, a onPaymentScheduled webhook will trigger when the next payment is made.

This webhook will trigger every time an invoice is added to the open (but held) payment for the biller. The program can see the list of accumulated invoices which are pending payment by querying the lp:payment-invoices link relation.

Path Parameters

Field Format Required? Description
onInvoicePaymentHeld URI Mandatory The URI you provided for the onInvoicePaymentHeld event.

Example Invoice Payment Held Webhook

{
    "id": "d76eac52-6b7f-4303-8c70-91ae2f4313f9",
    "created": "2020-01-30T03:49:25.548+00:00",
    "data": {
        "remitter": "tac",
        "billerId": "d5e6e8f7-bc9c-4a5b-8c60-8e8ffd665e26",
        "paymentId": "9a15ad10-dbf0-4ab6-83f1-e42019f188b5",
        "amount": 2322.23
    },
    "type": "settlement.payment.held",
    "_links": {
        "lp:payment-invoices": {
            "href": "https://api.payments.lanternpay.com/payment/9a15ad10-dbf0-4ab6-83f1-e42019f188b5/invoices"
        },
        "lp:webhook-error": {
            "href": "https://lanternpay.com/sample/webhook/8ad735a2-21a0-481a-9174-205817e95110"
        }
    }
}

Held Invoices

GET /payments/{paymentId}/invoices

This API can be used to retrieve a list of held invoices and claims for an open (and held) biller payment. The list of invoices returned will increase until the issue relating to the biller is resolved and the open payment is made.

Path Parameters

Field Format Required? Description
paymentId UUID Mandatory HICAPS’s unique reference for the payment, provided in the {onInvoicePaymentHeld} webhook.

Example Held Invoices Response

{
    "invoices": [
        {
            "invoiceId": "614f61e1-c62c-4d42-b0cf-3bf972030c21",
            "programInvoiceId": "47d6538e-de2b-4877-80cf-f293fbb36d30",
            "claimTransactions": [
                {
                    "claimId": "ea070557-757d-4127-8be6-690cb05b948a",
                    "amount": 234.23
                },
                {
                    "claimId": "54eadf24-aaba-4dbd-8d3b-f15f01c0ad3f",
                    "amount": 34.12
                }
            ]
        },
        {
            "invoiceId": "123ae1db-843e-461c-aab9-7dbaef7c83b6",
            "claims": [
                {
                    "claimId": "32170557-757d-4127-8be6-690cb05b948a",
                    "amount": 14.23
                },
                {
                    "claimId": "222adf24-aaba-4dbd-8d3b-f15f01c0ad3f",
                    "amount": 45.12
                }
            ]
        }
    ]
}

Invoice Overpaid

WEBHOOK {onInvoiceOverpaid}

The Invoice Overpaid webhook alerts the program that an invoice which has already had a payment made (for one or more claims on the invoice) has now had one or more claims on that invoice either cancelled or the funding amount reduced.

As the payment has already been made, this means that the biller has been overpaid by the program for part of the value, or the entire value, of the invoice. Generally, the program will contact the biller to rectify this overpayment, as per their internal processes.

Note that if an invoice is cancelled or the funding amount lowered before a payment instruction is issued to the bank, then HICAPS will adjust this amount accordingly and update the biller via the Invoice Status Updated webhook and no Invoice Overpaid webhook will trigger.

Path Parameters

Field Format Required? Description
onInvoiceOverpaid URI Mandatory The URI you provided for the onInvoiceOverpaid event.

Example Invoice Overpaid Webhook

{
    "id": "d64791b8-3c44-4695-aadd-891f07380a9a",
    "created": "1596012705",
    "data": {
        "billerId": "e6e7d33b-114e-473e-8e16-d00a9b05803a",
        "program": "tac",
        "invoiceId": "3a862a89-66e0-4c62-a2f0-850adb54fdf5",
        "overpaidClaims": [
            {
                "claimId": "98a26a4a-01d4-4f44-9357-945a565f955c",
                "amount": 123.45
            },
            {
                "claimId": "2e891e6a-7933-475d-8530-2fe391b41307",
                "amount": 87.15
            }
        ]
    },
    "type": "settlement.invoice.overpaid"
}