Provider API

Overview

The Provider API integrates HICAPS with the Provider’s invoicing application at the point of sale (e.g. using a Practice Management System) to send invoices to a program and receive adjudication results in real-time. Payment information of approved invoices that will be settled by HICAPS can then also flow directly to the Provider’s accounting application for easy reconciliation.

Claiming Overview

Philosophy

The Provider API is event-driven. The philosophy behind this approach is 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 CodeProgram NameProgram WebsiteHICAPS Terminal Required?
medicare-bulkbillMedicare - Bulk BillMedicare Bulk Bill External LinkNo
medicare-dvaMedicare - Dept. Veteran Affairs (DVA) / Dept. Veteran Affairs - Allied (VAA)Medicare DVA External LinkNo
medicare-pciMedicare - Patient Claiming InteractiveMedicare Claims Online External LinkNo
medicare-easyclaim-pcMedicare - Easyclaim - Patient Claims (Electronic)Medicare Easyclaim - Patient Claims External LinkYes
medicare-easyclaim-bulkbillMedicare - Easyclaim - BulkbillMedicare Easyclaim - Bulkbill External LinkYes
ndis-agencyNational Disability Insurance Scheme APIwww.ndis.gov.au External LinkNo
tacTransport Accident Commissionwww.tac.vic.gov.au External LinkNo
wsvWorkSafe Victoriawww.worksafe.vic.gov.au External LinkNo
mplMedibank Private Limitedwww.medibank.com.au External LinkNo
nibnib Health Fundwww.nib.com.au External LinkNo
wcqWorkCover QueenslandWorkCover QLD External LinkNo
icwaInsurance Commission of Western Australiawww.icwa.wa.gov.au External LinkNo
icareInsurance and Care NSWwww.icare.nsw.gov.au External LinkNo

Billers and Providers

A biller is the entity making the claim and receiving payment for it. A provider is the entity providing the service to the patient.

HICAPS distinguishes between the entity providing the service (Provider) and the entity submitting an invoice (Biller). An organization Provider (e.g. pharmacy, attendant carer, equipment supplier, etc) could embody both of these roles, while in most other cases separate Billing organizations would invoice on behalf of Providers. Direct interaction with HICAPS is exercised in the role of the Biller, who is also referred to as the user in this documentation.

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. Usually 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 Parameters section.

A patient is defined at the claim level (i.e. line item) for most programs, as defined in the Patient Parameters section. The only exception is for Medicare claims where patient is defined at the invoice level, as defined here.

Invoices and Claims

An Invoice is a holistic representation of the data submitted to a Program. An Invoice contains a collection of Claims, which represent line items on the Invoice.

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 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.

Note: Not all programs support predeterminations, so any predeterminations sent for the below programs will be ignored and we recommend you disable predeterminations for these programs:

  • National Disability Insurance Scheme (ndis-agency)
  • Medicare (all medicare-... sub-types)
  • WorkCover Queensland (wcq)
  • icare: Insurance and Care NSW (icare)

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 user as possible as a claim progresses through the journey of adjudication and payment. They help facilitate a digital conversation between the user and the program that occurs in real time via the Provider API.

States

A claim can only be in one of the states defined by HICAPS. For example, a claim will move through states: submitted → awaitingResponse → pending or approved or rejected. If a claim is in the approved state then the user 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. pending → approved) they notify HICAPS and we immediately notify the user.

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 user.

For example, a claim may be set to the pending claim state but this doesn’t tell the user why the claim is pending. So, using statuses, the program may choose to additionally 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 user 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 required 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 is likely to 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.

Provider API Claiming Process Diagram
Claim States

On submission to the program, the State of each claim becomes awaitingResponse. 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.

Provider API Claim States Diagram
Claim State Definitions
Adjudication Claim States

Claim states relating to normal adjudication flow.

StateEnum ValueDefinitionUser’s expected reaction to the state
AWAITING RESPONSEawaitingResponseClaim 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.
PENDINGpendingProgram 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. APPROVEDprovisionallyApprovedProgram 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.
APPROVEDapprovedThe 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
REJECTEDrejectedRejected 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.
Cancellation Claim States

Claim states relating to cancellation flow.

Note that a Biller can only request for a claim to be cancelled. The program will ultimately decide if they accept or reject the cancellation request.

If a request for cancellation is rejected by the program, then the program will respond with the previous claim’s state (e.g. approved)

StateEnum ValueDefinitionUser’s expected reaction to the state
AWAITING CANCEL RESPONSEawaitingCancelResponseThe 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 PENDINGcancelPendingThe 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.
CANCELLEDcancelledProgram 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 the claim to be cancelled and 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 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.

Depending on the program, there are three ways a payment can be made to a biller:

  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.
  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 trigger payment status update webhooks to notify the source application of the payment for the relevant invoices in that payment. See Invoice Payment Status Updated for more information on those webhooks.

For Non-HICAPS managed payments, #3 above, where the program pays the biller directly, HICAPS usually will not trigger a Invoice Payment Status Updated webhook for these invoices because the program has managed the payment without HICAPS involvement. There are some cases where the program will tell HICAPS about the payment they’ve made, in which case we will trigger this webhook to advise the user.

Payment Claim States

Each invoice also contains a payment state for the claims on the invoice. Because a single payment contains many invoices which may contain many claims, some of which may have been made from different applications, we advise the payment state at the per-invoice level. The payment states, for an invoice, are noted below.

See Invoice Payment Status Updated for more information.

StateEnum ValueDefinitionUser’s expected reaction to the state
SENTsentThe payment has been sent to the bank for processingBiller expects that the payment with the specified claims will have been included in a recent payment to their bank account (within banking timeframes)
FAILEDfailedThe payment has failedBiller expects to be contacted about how to rectify the issues with the bank account details
HELDheldThe payment has been heldBiller expects to be contacted about how to rectify the issues with the bank account details
OVERPAIDoverpaidThe payment has been made in excess of the approved claimBiller expects to be contacted about how to rectify the issues with the bank account details

Terminals

The Provider API supports integration with HICAPS terminals.

The integrated terminal functionality is being rolled out in phases as described below:

  1. Phase 1 (Complete, in pilot)
    • Query a biller’s linked merchant ID
    • Query which terminals are online for a given biller
    • Query the provider details loaded onto a given biller’s terminal(s)
    • Send a test (ping) to a nominated terminal and receive the results
    • Send a payment to a nominated terminal and receive transaction results (including surcharging if applicable)
    • Send a refund to a nominated terminal and receive transaction results
  2. Phase 2 (Complete, in pilot)
    • Submit a Medicare Easyclaim invoice and have it routed to a terminal, this includes the four claim types listed below:
      1. Fully paid claim
      2. Partially paid claim
      3. Unpaid claim
      4. Bulkbill claim
  3. Phase 3 (TBA)
    • Submit a Private Health Insurance (PHI) invoice for all PHIs and have it routed to a terminal
      • This includes overseas health cover (OVHC) claims for BUPA, Medibank Private and nib health funds.
    • Perform member verification and member card read/capture functions on the terminal
    • Pull transaction and merchant reports from terminal to your PMS

See the Terminals API specifications for detailed view on the Terminals API functionality - this section will be updated as we progress the phases above.

Currently (as at Feb, 2024), all integrated HICAPS terminals continue to require the installation of the HICAPS Connect application (see here External Link) on local workstations or terminal server to facilitate communication between the terminal and the HICAPS Provider API.

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 Provider API, as shown below:

  • Content Type (Content-Type) - must be application/json
  • Content Length (Content-Length) - even on empty POSTs, e.g. Content-Length=0
  • Host (Host)
  • Authentication (see below)
  • Application Identification (see below)
  • Message Correlation (optional - see below)

API Authentication

HICAPS’s identity service supports two OAuth 2.0 authentication flows:

  • authorization_code flow, where the user (biller) authorizes their PMS to submit invoices on their behalf. This authorization lasts 365 days and is our recommended flow
  • client_credentials flow, where the user (biller) stores their HICAPS issued client_id and client_secret in their PMS to authorize API calls.

Both flows are described below, and more details can be provided during integration, if required.

Authorization Code Flow

Authorization Code flow is our recommended flow when you have HICAPS billers as users in your application. In this flow they will login through our identity service and authorize you to perform API calls from your application on their behalf. Two key advantages of this flow is it is more secure because there is no manual effort required by the user to copy and paste client credentials into your application from the HICAPS portal, and you can embed the HICAPS login screen within your application so the user never has to leave your application to authorize your platform on the HICAPS Provider API.

This is the high level flow:

  1. The user is prompted to connect to HICAPS
  2. Your application redirects the user to our identity service login page
  3. The user logs into our identity server which automatically authorizes your application
  4. We then redirect the user back to your application and we will return a unique one-time code to you
  5. Your application will then retrieve security tokens, using this code, which you will store for that user
  6. These security tokens are then used to perform API actions such as submit invoice

This is what we will provide you:

  • A authorize endpoint URL, this is a unique URL we issue your application that you will redirect the user to when you prompt them to login to HICAPS to authorize your application - used in step 1 → 2, above
    • it is strongly recommended, for security reasons, that you also pass a unique and opaque state parameter in this URL which will be passed back to your callback URL on redirect so you can verify the response state in the redirect URL matches the one you sent to HICAPS in step 4, above. You can read more about this here here External Link.
  • A token endpoint URL that you will call to:
    1. exchange your application’s client_id and client_secret and user authorization code, received upon initial user authorization, for security tokens for that user
    2. retrieve a new id_token, using the refresh_token, when the id_token expires
  • A client_id and client_secret for your application - this authorizes your application in our identity service and is used in step 5, above

This is what we will need from you:

  • a HTTPS callback URL that accepts a code (GUID format) and a state passed as parameters in the URL (e.g. https://callback.url/path?code={GUID}&state={yourStateCode}) - used in step 4, above
Retrieving Security Tokens

This process is for authorization_code tokens only.

When a user authorizes your application you will receive a one-time code which you need to pass to our token endpoint URL, along with your application’s client_id and client_secret, which will retrieve three security tokens for that user, explained below:

  • access_token - this is not used and can be discarded
  • id_token - you will store this JWT formatted token against the user and use this token as the bearer token in the message header for each API action you perform (e.g. submit an invoice) for that user until it expires.
    • The id_token lasts 60 minutes in production and sandbox and can be used repeatedly within this time frame.
    • There is data inside the token which you need to store, as defined below:
      • the custom:BillerId is required as part of most API functions. You should always verify if a HICAPS billerId already exists against this user in your application that the stored billerId matches the one in the id_token - this is especially important if multiple users share a login in your application.
      • the auth_time is a record of when the user authentication took place, so this can be used to track the expiry time of the refresh_token. Each time you use a refresh_token to retrieve new id_tokens, the auth_time will remain the same so you can track this. If the user re-authenticates and you are issued a new refresh_token then this datetime stamp will update to reflect that.
      • the iat is the Issued At Time for this id_token so you can track its expiry and retrieve a new one before it expires.
      • the exp is the Expiry time for this id_token so you can track its expiry and retrieve a new one before it expires.
  • refresh_token - you will store this non-JWT formatted token against the user and use this token as a secret to retrieve a new id_token.
    • The refresh_token lasts 365 days in production and 1 hour in sandbox and can be used repeatedly within this time frame to retrieve a new id_token.
    • We recommend using the refresh token to retrieve a new id_token at least 5 mins before the id_token expires to ensure no permission errors.
    • Once the refresh_token expires, the user must re-authorize your platform with HICAPS’s identity service. We recommend triggering the user to re-authenticate ~2 weeks before the token expires (approximately 350 days from the auth_time in the id_token) to ensure there’s enough time if the user is on leave or has forgotten their password that they can re-authenticate before the tokens expire entirely and the user is impacted.
Authorization Code Base URIs

The authorization code API functions are relative to these base URIs:

EnvironmentURIDescription
Sandboxhttps://auth.sandbox.lanternpay.comThis is a pre-production environment you can use for testing.
Productionhttps://auth.lanternpay.comThis is the production environment.
How to retrieve initial security tokens after user authorization

POST /oauth2/token

Message PartTypeDetails
HeaderBasicAuthYour application’s client_id and client_secret, base64 encoded.
Bodyx-www-form-urlencoded“grant_type”: “authorization_code”
“code”: “{the code passed to your redirect URL}"
“redirect_uri”: “{your redirect URL}”
Example API Response Body
{
    "id_token": "eySraWQiOiJYZ0hvXC9ISWhoNFlyTkt5VStjd0l0c25tMFdWb0dlTkxRSnpSQVpnS2NsVT0iLCJhbGciOiJSUzI1NiJ9.eyJhdF9oYXNoIjoiVlpyanZ5QndTZEdULXFkNkFQRWFuZyIsInN1YiI6Ijk0NzA5ZDNlLTNhNTQtNGQ1Zi1hMWRhLWRkOGQwNzQyYzIxYSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJjdXN0b206Um9sZXMiOiJQcm92aWRlciIsImN1c3RvbTpQcm92aWRlcktleSI6ImQyZjhjNGMxLTdiZGUtMGUwOC0yOGNmLTUxMWFjMGIzZTNiYyIsImlzcyI6Imh0dHBzOlwvXC9jb2duaXRvLWlkcC5hcC1zb3V0aGVhc3QtMi5hbWF6b25hd3MuY29tXC9hcC1zb3V0aGVhc3QtMl83WHNKSzRlRGciLCJjb2duaXRvOnVzZXJuYW1lIjoiOTQ3MDlkM2UtM2E1NC00ZDVmLWExZGEtZGQ4ZDA3NDJjMjFhIiwiY3VzdG9tOlVzZXhddxZGYzNSIsImV2ZW50X2lkIjoiY2E2M2YzN2QtZTljNi00YzliLTgwMTgtMWZlZGM4MzM3M2YzIiwiY3VzdG9tOlByb2dyYW1zV2hpdGVsaXN0IjoibXBsO25pYjt3c3Y7bWVkaWNhcmUtZHZhO21lZGljYXJlLWJ1bGtiaWxsIiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE2NTE2NDQzOTYsImV4cCI6MTY1MTY0NDY5NiwiaWF0IjoxNjUxNjQ0Mzk2LCJmYW1pbHlfbmFtZSI6Ik8nSGFyZSIsImVtYWlsIjoiY2hyaXNmZWIyMDIyQGxhbnRlcm5wYXkuY29tIn0.bqmWzHYiMV71ge3rFlTtfQpOQipIbnqwJqbp_wi8YCXo9_7vWmlWsWMtoMhPoXRKwNwYh4UOWPB9aiEf4TgFub54UpQ8GySmP89IL0sq9Ss_Jocl2JE3OOIF6qlJaaA8NX4_NyqgJoP5qvZYIXBaZL2g4vbAQ04BHnrmn-_S93uZukOk8Gz0_r9Wy0xSX3Y6O3P_k4kzqyRdTFloVKqv5e0JdAj5nCRhOJDBLyn3SWq4rB2frWknUeprOQVPv-iipXHUCUIic385b4V6MhBfqGEjD8HWb89K-h-1VPVcrVZke_YKVp5Pyys1H-VvQagy09XKwqjJ2fiXKrMhrrSpbw",
    "access_token": "eyAraWQiOiJhc3hYNHlCbDI4U1wvdERWTndxOWt1UlQ3UHMycCtkekllU01iU0RlTTIrUT0iLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI5NDcwOWQzZS0zYTU0LTRkNWYtYTFkYS1kZDhkMDc0MmMyMWEiLCJldmVudF9pZCI6ImNhNjNmMzdkLWU5YzYtNGM5Yi04MDE4LTFmZWRjODMzNzNmMyIsInRva2VuX3VzZSI6ImFjY2VzcyIsInNjb3BlIjoib3BlbmlkIiwiYXV0aF90aW1lIjoxNjUxNjQ0Mzk2LCJpc3MiOiJodHRwczpcL1wvY29nbml0by1pZHAuYXAtc291dGhlYXN0LTIuYW1hem9uYXdzLmNvbVwvYXAtc291dGhlYXN0LTJfN1hzSks0ZURnIiwiZXhwIjoxNjUxNjQ0Njk2LCJpYXQiOjE2NTE2NDQzOTYsInZlcnNpb24iOjIsImp0aSI6ImM0YThmZDZiLTIxYWYtNGY0Zi04MWU0LTIxZWJhYzZiMjE0NyIsImNsaWashCI6IjNjYjRjZ3NvMTFza2hucDMzYmxmaWI4bXZjIiwidXNlcm5hbWUiOiI5NDcwOWQzZS0zYTU0LTRkNWYtYTFkYS1kZDhkMDc0MmMyMWEifQ.i7Qtl-ES0je7pRueDdEQ1uAxu8AIsO69LYiQ_Ql6HoEQqX2QKBS4rLj4S4MXsRvm-_iwuO0w7XwOdafqOl6h53i6xnfuos7_C1gUjtNlH5Eu5sjnSa4G3Q9Qs0RxT7DeLnaL_B9yUZg6DRBVw8B3xvtUl1x7lArS-p1rPhQn1Q3lqcbc7oHMoiDcpwTlTFXl9KtsZfe8_zRVnQSyptYMrc74NabC-Z5xkWQLLTI1S0NwccR0drSxcch2PU88mup3huUkrzYaYtr4D36SsbaO3UCKuGuTzOMRKzHVL0FQ4-38mnP9OYacp_ea9E0q0tV-_rI9_YbGLNZb39e0U8odxw",
    "refresh_token": "eyZjdHkiOiJKV1QiLCJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAifQ.P1YQZDxJtkRwV6lmR8Ts_GHmTvXAgdW9haCwizKU-QPzKWggPVetkW8q6wM2L9Agcg_B5l0ON-b8sJlHixpwSgcjjOvPb44mEy6xOzSCFqFgDwcmQ7I2-PVyl72x_GigeT5653mbYdDUgAi91wsTf6yqa03jc87E38iOads1RLyGikbtwUpm6EeuNO4vCZnoq8sIc1WHQau_zWDAry6DsUuLUuV8jhIxRgcr2Uvt-K9J5ZmPGiqjQ3y4kMg6qPL0cdqCcPo_CwXzHp39HMGJ9c5_NskBJ8AGKQEM4BMHILsLp5fWi3Jwuh5kE-KeNwRITSDv2H-G2u77FmZGNmm0kA.19cSDwMA_QTfZesZ.5iAV9VPfxdSu-HhV8Um-q8G9r0iwheIH3w8wUW8wNM0spfJiagJ40tjfpbc9entAm90-9HZBD_aKTBorm_cBnaRzx4sWDHXK36lc4RhTfdtZszVrk8KRR0KAiIjd6Mf9156zM4woSViBYmT7rwaSplurtLaOIpXO7qLJwbj9jeP4tVLpcfWlaH9dXbcZz4Lg3i2dDcHfZZtaFC-bBY29Ptbyuo8hJzcWht8KFLsiiOKP1IiSd03WZjo-J5dhoF13dYPaCMuvLu6lpJWTbJbzGd4g8QknPhY_uh9HyYivkwUhUumyrjFKUdtYzOzSdJJIK6p0hNR9gYQ4auvUCELpwmTgdW34Xtj5OVJPLPtwiEITF_4bPEgqYR4olCCR3crGtMioDE-kfe6g_1sq5hEwmMu4qvDsqPjw9iWkMBJn23sWuFAnvPOGfMToOJeNeHXjNEl2Pbxa8u5r7Kr5pmlTkPbYeECHMuwGXDFZb_0ad0qQz-ZmRzrOzPnyCRkT5nymbpkOmCl91lQoHdGz4aqrsfp3fwrOYEKOk6HO2E3JYJdrAHgJM7UkoloOF-L0B4tyjkeGYmF5rCpYoglNkPp7AvN0megFJb1Td3rLjK7rvdlepkMCNeUYLtRGNpirXVndcYC8XOquNwvdfAfHnrLCC_zHxorY6J72E3nByrT5X00hIk6NQmY0PIcJ_Yo6U6pOODZ3sY5-ljnrTXFVxoT1OWUYnx-i6y_65rmigEUBZTtB8JqBbUFgBMWHBCm268U1uXLb8W_EmA72mxw0dyU1FrKBa5iqEWp4irYysjiqmF2jwGJ6zWPqn0RCuyw3Q1wyxqGfGKEqU6QP6A-aWnX4L_I9GM-9N6LXmO7btq_DaSO2Xp1bxdj38V-6kTLvYV2S412HkPBTXihKP0QIfP9FTV8mDQdkUOTriPjIjIALjTomKHUlYGJuQsPcQGUWarAHQmcFG8fP0gVTrLqs6M45rE56buduIccQh3prhCcfS2fDcnlxxgNCkieTD7yXKJPRoFI7LmsVbYQb_8t-TA1Lhp12loGK9lPrS4YIni4b1oe6BtpcFbH-wLgatpc61Qte_SzZzAfRvUBcxk8ltqof3nJpqn8Cy_7I4Jtc4sl9uZsHdvKOS4b1DYQpJn8UrszGezI_L3cObFeixgGWHxkTRNeF_f-9Spos00Q-aEXnQMhhicUE7gWGDjQs8UwkiqgNSByLZm3BxMOARe-r896AeLASR0KNAlgnPVXqLW_-HnfCTJ-s7oP37ARxPMpOZYztgWYjqMqtihTCA4KIfWF-eOcWDNGcG7xRd-gkFNjJB0nrXU3ieFUdxlTReUKd.tmDJ8atGICIYWdXPEp-f2A",
    "expires_in": 300,
    "token_type": "Bearer"
}
How to use the refresh token to retrieve a new ID token

POST /oauth2/token

Message PartTypeDetails
HeaderBasicAuthYour application’s client_id and client_secret, base64 encoded.
Bodyx-www-form-urlencoded“grant_type”: “refresh_token”
“refresh_token”: “{refresh_token}”
Example API Response Body
{
    "id_token": "eyZraWQiOiJYZ0hvXC9ISWhoNFlyTkt5VStjd0l0c25tMFdWb0dlTkxRSnpSQVpnS2NsVT0iLCJhbGciOiJSUzI1NiJ9.eyJhdF9oYXNoIjoiZzVDMXJRN2tCTUItMjFwRDZUY0dUQSIsInN1YiI6Ijk0NzA5ZDNlLTNhNTQtNGQ1Zi1hMWRhLWRkOGQwNzQyYzIxYSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJjdXN0b206Um9sZXMiOiJQcm92aWRlciIsImN1c3RvbTpQcm92aWRlcktleSI6ImQyZjhjNGMxLTdiZGUtMGUwOC0yOGNmLTUxMWFjMGIzZTNiYyIsImlzcyI6Imh0dHBzOlwvXC9jb2duaXRvLWlkcC5hcC1zb3V0aGVhc3QtMi5hbWF6b25hd3MuY29tXC9hcC1zb3V0aGVhc3QtMl83WHNKSzRlRGciLCJjb2duaXRvOnVzZXJuYW1lIjoiOTQ3MDlkM2UtM2E1NC00ZDVmLWExZGEtZ123iwiY3VzdG9tOlVzZXJLZXkiOiJkYzE4MzU0Zi0wZWExLTRjN2QtODI1Yi0yZGNjMWE2NDNjODkiLCJnaXZlbl9uYW1lIjoiQ2hyaXMiLCJhdWQiOiIzY2I0Y2dzbzExc2tobnAzM2JsZmliOG12YyIsImN1c3RvbTpCaWxsZXJJZCI6IjBlZTBmMThlLTc1N2YtNDI3NS1hYTk0LTdjZDZkYWQ3ZGYzNSIsImV2ZW50X23342QtZTljNi00YzliLTgwMTgtMWZlZGM4MzM3M2YzIiwiY3VzdG9tOlByb2dyYW1zV2hpdGVsaXN0IjoibXBsO25pYjt3c3Y7bWVkaWNhcmUtZHZhO21lZGljYXJlLWJ1bGtiaWxsIiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE2NTE2NDQzOTYsImV4cCI6MTY1MTY0NzM5MSwiaWF0IjoxNjUxNjQ3MDkxLCJmYW1pbHlfbmFtZSI6Ik8nSGFyZSIsImVtYWlsIjoiY2hyaXNmZWIyMDIyQGxhbnRlcm5wYXkuY29tIn0.dNm4fPIQtwjvf0F0oBOMmstE-2ISgVr3Vr8ZaFIAU43N0iMQwcsUQrwJPaJJ0G-Txn5IVgOPLsrXdJWlbE9tP0gLjaxBhmCB-h-DYapFXO62ITNYVFxFIwJSkHBlk7p2--YBMqDBhsem6BnYVeAbrjUPaBhPXqqOhLMZOLgmoHcDqBTX8px5uIWOC97J14q1OViAfzvGE5imgVeWcr6HnM5QJGLkEa2u0mNqSEQLwEmfIkCz7tbE87YgsFOSdxzxFxIYTr4Kiripu2s7Wn_ahOwmWNDgvAfLzdEYlHrpnA-0uN-MbtZ1xEvZLCXvEwZtGsoFzi3X65x5YeDYB4eDpQ",
    "access_token": "eyAraWQiOiJhc3hYNHlCbDI4U1wvdERWTndxOWt1UlQ3UHMycCtkekllU01iU0RlTTIrUT0iLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI5NDcwOWQzZS0zYTU0LTRkNWYtYTFkYS1kZDhkMDc0MmMyMWEiLCJldmVudF9pZCI6ImNhNjNmMzdkLWU5YzYtNGM5Yi04MDE4LTFmZWRjODMzNzNmMyIsInRva2VuX3VzZSI6ImFjY2VzcyIsInNjb3BlIjoib3BlbmlkIiwiYXV0aF90aW1lIjoxNjUxNjQ0Mzk2LCJpc3MiOiJdfwczpcL1wvY29nbml0by1pZHAuYXAtc291dGhlYXN023uYXdzLmNvbVwvYXAtc291dGhlYXN0LTJfN1hzSks0ZURnIiwiZXhwIjoxNjUxNjQ3MzkxLCJpYXQiOjE2NTE2NDcwOTEsInZlcnNpb24iOjIsImp0aSI6IjMwYTVlZGRiLWRlODktNDkxNC1iZjliLThiZTA0Yjc5MDY5NCIsImNsaWVudF9pZCI6IjNjYjRjZ3NvMTFza2hucDMzYmxmaWI4bXZjIiwidXNlcm5hbWUiOiI5NDcwOWQzZS0zYTU0LTRkNWYtYTFkYS1kZDhkMDc0MmMyMWEifQ.eEp_KN0yElfNUQcmc1ekMqJydVybHyyCdksiSX9FVn5aeHr5JKZdsoqBH6W-OR36yF3D-i6edfFRDX5QlLg4So8_5sNSMYCJkoPmROC1Fe4GnuxflcV3M_32yAuhGZrzrKuYttCsYEqpZ3yzPqE1dOqP2SWQy4kGz5L8insBHNj2YPMv7mkofXY0SvxEKu_ebkIsnx3l8P7_3X4kgZajsnq1z1x1Fi5Rt4bB3o8vwNGfYTvD8tWvxhjARPhNrCV26HM79zblGZxP2YqiyfbfjKilauyjbm65yrUAmUPpuwGq0qIcT069PGEb_Wi8aM63BxsdIDPMjV_oHpplSU8yKA",
    "expires_in": 300,
    "token_type": "Bearer"
}
Client Credentials Flow

Client credentials flow involves the user copying their client_id and client_secret from the HICAPS portal and storing them securely in your application. Whenever the user wants to perform an API action, you will retrieve a security token from HICAPS’s identity service for the user and pass that in the API call to HICAPS.

This is the high level flow (assumes the user has already copied their HICAPS credentials into your application):

  1. Your application retrieves a security token, using the user’s client credentials, which you will store for that user
  2. This security token is then used to perform API actions such as submit invoice

This is what we will provide you:

  • A token endpoint URL that you will call to exchange this user’s client_id and client_secret for a security token for this user
Retrieving Security Tokens

This process is for client_credentials tokens only.

Once the user has stored their client_id and client_secret in your application you are then able to retrieve a security token for the user, explained below:

  • access_token - you will store this JWT formatted token against the user and use this token as the bearer token in the message header for each API action you perform (e.g. submit an invoice) for that user until it expires.
    • The access_token lasts 60 minutes in production and sandbox and can be used repeatedly within this time frame.
    • We recommend retrieving a new access_token at least 5 mins before it expires to ensure no permission errors.
    • There is data inside the token which you need to store, as defined below:
      • the custom:BillerId is required as part of most API functions. You should always verify if a HICAPS billerId already exists against this user in your application that the stored billerId matches the one in the access_token - this is especially important if multiple users share a login in your application.
      • the iat is the Issued At Time for this access_token so you can track its expiry and retrieve a new one before it expires.
      • the exp is the Expiry time for this access_token so you can track its expiry and retrieve a new one before it expires.
Client Credentials Base URIs

The client credentials API functions are relative to these base URIs:

EnvironmentURIDescription
Sandboxhttps://api.auth.sandbox.lanternpay.comThis is a pre-production environment you can use for testing.
Productionhttps://api.auth.lanternpay.comThis is the production environment.
How to retrieve security tokens

This endpoint is used to retrieve both the initial security tokens when the biller is first onboarded, and also used repeatedly going forward whenever a new security token is required (i.e. when the existing token expires) - if the user is active, we recommend you retrieve a new security token at least 2-5 minutes before the current token expires to ensure there is no interruption in user authentication.

POST /oauth2/token

Message PartTypeDetails
HeaderBasicAuthN/A - no header auth is used
Bodyx-www-form-urlencoded“scope”: “openid”
“client_id”: “{the user's client id}"
“client_secret”: “{the user's client secret}"
“grant_type”: “client_credentials”
Example API Response Body
{
    "access_token": "eyzraWQiOiJYZ0hvXC9ISWhoNFlyTkt5VStjd0l0c25tMFdWb0dlTkxRSnpSQVpnS2NsVT0iLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1NWE5OGZkNi00OWNhLTQyNjAtYjBjMS1iNWIxZjZmYWIyM2QiLCJlbWFpbF92ZXJpZmllZCI6dHJ1ZSwiY3VzdG9tOlJvbGVzIjoiUHJvdmlkZXIiLCJjdXN0b206UHJvdmlkZXJLZXkiOiJjZjljOWNiOC1kODk5LTA1ZGQtMzg3YS1iNTA5ZmMxZjY3YWEiLCJpc3MiOiJodHRwczpcL1wvY29nbml0by1pZHAuYXAtc291dGhlYXN0LTIuYW1hem9uYXdzLmNvbVwvYXAtc291dGhlYXN0LTJfN1hzSks0ZURnIiwiY29nbml0bzp1c2VybmFtZSI6IjU1YTk4ZmQ2LTQ5Y2EtNDI2MC1iMGMxLWI1YjFmNmZhYjIzZCIsImN1c3RvbTpVc2VyS2V5IjoiYzE3YzZkMzYtYWRlNi00N2E4LTkyZWUtYzlkZjI2YzhiODlmIiwiZ2l2ZW5fbmFtZSI6IkFQSSBD12llbnQgZm9yIEJpbGxlciBOdW1iZXIgTFAtQkxSLTgyWFRZSFc5IiwiY3VzdG9tOkNsaWVudElkIjoiN2I2OWRiYjEtYmFmNy00MjcyLWFkMTAtYzZlZDJmNWQyMDA2IiwiYXVkIjoiM2x0MXMwcTUxcHIyaHNoNWh0aXJhMmlhYWsiLCJjdXN0b206QmlsbGVySWQiOiIwZWUwZjE4ZS03NTdmLTQyNzUtYWE5NC03Y2Q2ZGFkN2RmMzUiLCJldmVudF9pZCI6Ijc3NGNjNTc0LTdiMTgtNDljZi1iN2Y1LTdmNzY0ZWUzNzsadwIsInRva2VuX3VzZSI6ImlkIiwiYXV0aF90aW1lIjoxNjUxODE2Nzc5LCJleHAiOjE2NTE4MjAzNzksImlhdCI6MTY1MTgxNjc3OSwiZW1haWwiOiI3YjY5ZGJiMS1iYWY3LTQyNzItYWQxMC1jNmVkMmY1ZDIwMDZAbGFudGVybnBheS5jb20ifQ.bjyqcl_7Sf0DMS4ewF2rA5WTpXR6w3bAQGp3UiMD3bflvC5mFsTlf-s0RTxsnow0Zpr-foa9a7HaAi3dujEBedNhR46P4KQivlK9MbXGn-8iosflgI0SqR0zWNmf4o-9eeDVubYZ4hgjIG8mspp-i6DVJ_G5DlMN57fhPJDiQ8pitp3nuBIjwVbiTWFKfHbqsmIcRoRDS-5fr8znQQwwahfRwLPv4qmIC_mabyLXMdGx-8cCmsgvaw_-9ExtRirsHR-kf20I_lYVU-NTK2hV5vxlGgebTF546BCPt11OD_43axjDa0cItOlJeqd4oYOFACZcWEQ2Gh2KW7Ax0lVGVw",
    "expires_in": 3600,
    "token_type": "Bearer"
}

Application Identification

HICAPS requires the client application to identify itself, separately to identifying the authenticated user. This identifier is associated with a product, and ideally, a version of the product. This identifier is used to ensure that webhooks are delivered to the correct source application.

To identify your client application, each API request must include this HTTP header as a name/value pair, for example: X-LanternPay-Api-Client-Id = {some guid}

The value to include in the X-LanternPay-Api-Client-Id will be issued by HICAPS during onboarding.

Message Correlation

In many cases some webhooks/exchanges can be difficult to unambiguously correlate back to the originating request. To address this issue HICAPS accepts the provision of a unique correlation identifier as a name/value in the HTTP header of each API call, if no correlation identifier is provided, then HICAPS will provide one. This name/value pair should be provided in the following format:

NameValue
X-LanternPay-Correlation-IdThere are two options to consider when implementing this function:
  • You populate a valid, unique GUID that unambiguously identifies each call or
  • HICAPS will respond with a valid GUID to each call made that you can store to unambiguously correlate webhooks or messages related to the original exchange

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 CodeOutcome
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.

FieldFormatRequired?Description
typestringConditionalA link to online documentation describing the type of error.
titlestringMandatoryA description of the error.
invalidParamsArray of Invalid ParametersConditionalAn array of fields with errors

Invalid Parameters

FieldFormatRequired?Description
namestringMandatoryThe 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.
reasonstringMandatoryThe reason for the error.

Example API Error Payload

{
    "type": "https://example.net/validation-error",
    "title": "Your request parameters didn't validate.",
    "invalidParams": [
        {
            "name": "unitPrice",
            "reason": "'unitPrice' must not be empty."
        },
        {
            "name": "program",
            "reason": "'program' code is not known."
        }
    ]
}

Webhooks

Webhooks allow HICAPS to signal to the user that an event has occurred within the HICAPS platform. During onboarding, you will define API endpoints that HICAPS will deliver webhooks to for various events.

FieldDescription
idA 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 send the same event multiple times if it fails to get positive acknowledgement of a request.
createdThe date and time of the event in Unix Epoch Time format.
dataA 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.
typeA string defining the type of the webhook
_linksA 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 webhook handler should handle the request asynchronously.

This means responding very quickly with a success status code (202 Accepted is preferred). This style ensures that in the event of heavy load, 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 when HICAPS attempts to deliver a webhook. HICAPS actions for each status code are as below.

Status CodeHICAPS 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.

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.

WebhookDelay (s)Time (s)
100
20.080.08
30.320.4
40.721.12
51.252.4
624.4
………
2338.72303.6
2442.32345.92

Notification Cache

If your application is based on-premise, or you otherwise cannot receive webhooks pushed directly to your application (e.g. no web-accessible webhook handler, firewall blocking, etc.) then we have a Notification Cache service that can be used instead of receiving webhooks.

The notification cache specification is detailed below, but broadly speaking it provides a queuing mechanism for notifications that are pending delivery to your application. The service allows you to connect and download (i.e POLL/PULL, rather than PUSH) any queued messages and then explicitly delete messages from the queue once you’ve processed them.

The service will cache notifications into individual queues based on biller ID which allows you to increase or decrease polling frequency on a per-biller basis, based on individual biller activity. For example, if a specific biller is actively creating and submitting invoices then you should increase your polling frequency for that biller’s queue; when that biller logs off or is dormant, you can reduce the polling frequency to reduce API chatter and resource cost.

The notification cache is not designed to be permanent storage or an archive of notifications, and as such the queues are ephemeral and individual notification messages will be automatically deleted after 14 days.

As described above in Asynchronous Webhook Handlers, it is expected that whenever possible notifications are processed by your application asynchronously. This means that notifications are retrieved rapidly and stored locally for processing.

If this is not possible in your application, the notification cache supports retrieval of messages in batches ranging from one message to 10 messages at a time, allowing you to retrieve one at a time if processing synchronously, and as much as 10 if processing asynchronously.

Whenever a message is retrieved, it will become invisible in the queue for 30 seconds. If the message is not deleted within that window, then it will become visible again and may be re-downloaded in a future request. This is why you need to ensure you explicitly delete a message once you’re received it.

Custom Instance Queues

Notification Cache queues are created using a combination of your X-LanternPay-Api-Client-Id + billerKey to ensure queues are created unique to individual billers, to keep messages segmented accordingly.

However, in some cases, especially with terminal flows, there may be multiple workstations that are polling for messages for the same biller. If this occurs, one workstation may be polling and locking messages intended for the other workstation which can cause issues with message visibility.

To prevent this, we allow our partners to add an optional third unique identifier (along with the API Client Id + Biller Key) to the API request which we use to create unique queues using that additional level of uniqueness. This is controlled by a header value that you generate and pass in the header of every API request. This API header is X-Hicaps-Api-Client-Instance-Id and must be a unique string (we recommend GUID format), e.g. X-Hicaps-Api-Client-Instance-Id = ed741fa6-133c-4cda-8fc6-2daa2ba70b4b.

For example, if you have a copy of your PMS application installed on workstation A, and another copy on workstation B, and they are both performing transactions for the same biller, the unique X-Hicaps-Api-Client-Instance-Id that each application would be sending ensures they get their own individual notification cache queues - instead of sharing a queue based on just the biller ID.

Furthermore, this doesn’t have to be used as application instance level identifier, it could be at site level, or a server level, or indeed a combination of these as you see fit.

Note that this X-Hicaps-Api-Client-Instance-Id is only required when using Notification Cache, and you must also still pass the X-LanternPay-Api-Client-Id header mentioned in the Application Identification section above.

Notification Cache Base URIs

The base URIs for the Notification Cache API functions are different to the Provider API base URIs, and are defined below:

EnvironmentURIDescription
Sandboxhttps://api.notificationcache.sandbox.lanternpay.comThe is a pre-production environment used for testing.
Productionhttps://api.notificationcache.lanternpay.comThis is the production environment.
Get Notifications

GET /billers/{billerId}/notifications

Path Parameters
FieldFormatRequired?Description
billerIdUUIDMandatoryHICAPS’s unique reference for the Biller.
Query Parameters
FieldFormatRequired?Description
maxNumberOfMessagesintegerOptionalThe maximum number of messages to retrieve from the queue, in one request.
Default = 1, minimum = 1, maximum = 10
Get Notifications Response Parameters

The notification cache responds with an array of notifications, defined below.

FieldFormatRequired?Description
receiptHandlestringMandatoryThis is a string that represents the serving of this particular notification. This is important to maintain congruency and control when deleting notifications - we will only allow a notification to be deleted if the most recent receiptHandle is provided. This is to ensure that if the same message is retrieved multiple times, only the most recent receiptHandle can be used to delete the message.
notificationNotificationMandatoryThe notification object, defined in the table below.
Notification Object Parameters
FieldFormatRequired?Description
idUUIDMandatoryThis is the unique notification ID issued by HICAPS for this notification and is required when deleting notifications. You should also store a list of notification IDs to ensure when processing notifications you can detect duplicates.
messageobjectMandatoryThe message is the original webhook that was generated and sent to the queue (instead of delivered directly), the schema of the message object depends on what notification was triggered. The message.type will inform how you parse this message object.
Example Get Notifications Response

This example shows a retrieval of one notification from the queue that happens to be an invoice status updated webhook (seen in the notifications[].notification.message object.)

HTTP-200 - below returned if messages found for this biller.

If no messages are available you will receive an empty notifications array.

{
    "notifications": [
        {
            "receiptHandle": "MbZj6wDWli+JvwwJaBV+3dcjk2YW2vA3+STFFljTM8tJJg6HRG6PYSasuWXPJB+CwLj1FjgXUv1uSj1gUPAWV66FU/WeR4mq2OKpEGYWbnLmpRCJVAyeMjeU5ZBdtcQ+QEauMZc8ZRv37sIW2iJKq3M9MFx1YvV11A2x/KSbkJ0=",
            "notification": {
                "id": "{guid}",
                "message": {
                    "id": "d76eac52-6b7f-4303-8c70-91ae2f4313f9",
                    "created": 1565140165,
                    "data": {
                        "invoiceId": "d5e6e8f7-bc9c-4a5b-8c60-8e8ffd665e26",
                        "claimStatuses": [
                            {
                                "claimId": "4d01ce18-bb10-4390-af84-3a2c56e2dc44",
                                "billerClaimId ": "1",
                                "benefit": 120,
                                "adjudications": [
                                    {
                                        "amount": 120,
                                        "reason": "Paid in full"
                                    }
                                ],
                                "state": "approved"
                            }
                        ]
                    },
                    "type": "claiming.invoice.updated",
                    "_links": {
                        "lp:webhook-error": {
                            "href": null
                        }
                    }
                }
            }
        }
    ],
    "approximateNumberOfMessages": 1
}
Delete A Notification

DEL /billers/{billerId}/notifications/{notificationId}

Path Parameters
FieldFormatRequired?Description
billerIdUUIDMandatoryHICAPS’s unique reference for the Biller.
notificationIdUUIDMandatoryThe unique reference for the notification retrieved from the cache.
Delete A Notification Body Parameters
FieldFormatRequired?Description
receiptHandlestringMandatoryThe receiptHandle string provided by the notification cache representing the serving of this particular notification. To successfully delete a notification only the most recent receiptHandle will be accepted.
Example Delete Notification Request
{
    "receiptHandle": "MbZj6wDWli+JvwwJaBV+3dcjk2YW2vA3+STFFljTM8tJJg6HRG6PYSasuWXPJB+CwLj1FjgXUv1uSj1gUPAWV66FU/WeR4mq2OKpEGYWbnLmpRCJVAyeMjeU5ZBdtcQ+QEauMZc8ZRv37sIW2iJKq3M9MFx1YvV11A2x/KSbkJ0="
}
Example Delete Notification Response

HTTP-200

Program Extensions

Program Extensions are program-specific functions of the API, such as the NDIS service booking APIs, that are not available for all programs or otherwise sit outside the standard claiming flow.

Detailed information about the extensions that are currently available, including technical specifications, are listed under the API Resources section of the documentation.

Note: some extensions have unique base URLs which are described where relevant in the sections below.

Current extensions available are:

API Resources

Base URIs

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

EnvironmentURIDescription
Sandboxhttps://api.providers.sandbox.lanternpay.comThis is a pre-production environment used for testing.
Productionhttps://api.providers.lanternpay.comThis 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 an access token and then you can navigate the API using the link relations present in the root response. This resource can also be used to ensure the Provider 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.providers.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"
        },
        "lp:submit-invoice": {
            "href": "https://api.providers.lanternpay.com/billers/{billerId}/invoice",
            "templated": true
        },
        "lp:submit-predetermination": {
            "href": "https://api.providers.lanternpay.com/billers/{billerId}/predetermination",
            "templated": true
        },
        "curies": {
            "name": "lp",
            "href": "https://docs.lanternpay.com/reference#{rel}",
            "templated": true
        }
    }
}

Invoices

This resource allows submission of an invoice for processing and adjudication by the program.

Submit Invoice

POST /billers/{billerId}/invoice

Path Parameters

FieldFormatRequired?Description
billerIdUUIDMandatoryHICAPS’s unique reference for the Biller.

Invoice Body Parameters

FieldFormatRequired?Description
billerInvoiceIdstringConditionalThe biller’s unique invoice Id. This is strongly recommended and we will provide you with a globally unique invoiceId in the synchronous response mapped to your billerInvoiceId and from there you can correlate all subsequent updates back to the invoice entity in your system.
programstringMandatoryShort name of the target program.
See the list of Program codes here.
responsePrioritystringMandatoryIndicates to the Program the expected SLA for response.
Values include: stat (immediately/real time), normal (with best effort), deferred (later, when possible).
createddateTime
YYYY-MM-DDTHH:mm:ss.SSS±HH:mm
MandatorydateTime of creation of this entity in the PMS.
invoiceNumberstringConditionalThe invoice number which the user provided for this claim.
Note: for Medicare Easyclaim invoices, this field has a max length of nine characters on the terminal. Characters beyond nine will be discarded.
invoiceDatedate
YYYY-MM-DD
ConditionalDate of original invoice
memberMemberMandatoryThe entity who the claim is for.
patientPatientConditionalThe patient parameters at the invoice level are for medicare claims only.
For all other programs, use the patient parameters at the claim level.
invoiceCustomFieldsInvoiceCustomFieldsConditionalOther invoice-level fields associated with this invoice, as required by the program.
claimsAn array of ClaimsMandatoryList of claims (invoice line items).

Member Parameters

FieldFormatRequired?Description
memberNumberstringMandatoryMember’s identifier, as issued by the Program.
givenNamestringConditionalThe member’s first name.
Note: Where a member has only one name, that name should be entered into the familyName field and the word Onlyname be entered in the givenName field.
familyNamestringConditionalThe member’s last name.
birthDatedate
YYYY-MM-DD
ConditionalThe members date of birth.
genderstringConditionalValues include: male, female and unspecified.
emailstringConditionalThe email address of the member.
memberCustomFieldsMemberCustomFieldsConditionalOther 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.

FieldFormatRequired?Description
personIdentifierstringConditionalThis 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 first (or only) name on the card, then use "1" as the string value.

Patient Parameters

The patient parameters at the invoice level are for medicare claims only. For all other programs, use the patient parameters at the claim 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.

FieldFormatRequired?Description
memberNumberstringMandatoryMember’s identifier, as issued by the Program.
givenNamestringConditionalThe patient’s first name.
Note: Where a patient has only one name, that name should be entered into the familyName field and the word Onlyname be entered in the givenName field.
familyNamestringConditionalThe patient’s last name.
birthDatedate
YYYY-MM-DD
ConditionalThe patient’s date of birth.
genderstringConditionalValues include: male, female and unspecified.
patientCustomFieldsPatientCustomFieldsConditionalOther fields associated with this patient, as required by the Program.

PatientCustomFields Parameters

The patientCustomFields parameters at the invoice level are for medicare claims only. For all other programs, use the patientCustomFields parameters at the claim level.

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

FieldFormatRequired?Description
personIdentifierstringConditionalThis 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.

InvoiceCustomFields Parameters

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

FieldFormatRequired?Description
medicareMedicareConditionalThese fields are required for some Medicare claims.
referralReferralConditionalThese fields are required for certain claims.
medicareDvaMedicare DVAConditionalThese fields are required for Medicare DVA claims.
ndisNDISConditionalThese fields are required for customers who have access to the NDIS Payee module
wcqWCQConditionalThese fields are required for WorkCover QLD claims

Medicare Invoice Parameters

FieldFormatRequired?Description
payeeProviderNumberstringConditionalThe provider number of the payee provider, if different from the servicing provider.
cevRequestIndicatorstringConditionalThe Concession Entitlement Verification indicator to determine if the patient is entitled to a concession. Must be Y or N. Only required for Medicare Easyclaim Bulk Bill claim types.
isFullyPaidByClientbooleanConditionalSet to true to indicate if the entire invoice amount has been paid by the client, otherwise set to false.
If the client has paid a partial amount, set to false and use the amountPaidByClient field at the claim line-item level to indicate how much was paid, per claim line item.

Referral Parameters

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

FieldFormatRequired?Description
issueDatedate
YYYY-MM-DD
ConditionalThe referral issue date as a string.
overrideCodestringConditionalUsed when referral services were provided without a referral. Valid values are L (lost), E (emergency), H (hospital), N (not required), R (remote exemption).
periodTypestringConditionalThe type of referral:
S = Standard (12 months from a GP and 3 months from a Specialist)
N = Non-standard
I = Indefinite
periodstringConditionalValue represents number of months, e.g. "7" for seven months.
Required only if periodType is "N"
referralProviderReferral ProviderMandatoryProvider object contains information about the referring provider.

Referral Provider Parameters

FieldFormatRequired?Description
providerNumberstringMandatoryThe referring provider’s Provider Number
providerNamestringConditionalThe referring provider’s Name
providerTypestringConditionalValid values include:
G General Practitioner
S Specialist (e.g. Physiotherapist)

Medicare DVA Parameters

FieldFormatRequired?Description
disabilityDisabilityMandatoryRequired for Medicare DVA claims.

Medicare DVA Disability Parameters

FieldFormatRequired?Description
descriptionstringMandatoryThe 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.
isRelatedbooleanMandatoryMust 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.

FieldFormatRequired?Description
payeeInvoicebooleanConditionalWhen set to true and the Provider has access to the Payee module, then a payment will be attempted for each successful claim.
payeeNDIS payeeConditionalRequired when payeeInvoice is set to true. Contains the payee information.

NDIS Payee Invoice Parameters

FieldFormatRequired?Description
namestringConditionalThe name of the Provider. Required when payeeInvoice set to true.
emailstringConditionalThe email address of the payee, this controls where the remittance will be sent. Required when payeeInvoice set to true.
referencestringOptionalThe customers reference for the payee.
bsb6 digitsConditionalThe BSB number of the payee bank account. Required when payeeInvoice set to true.
accountNumber1 to 9 digitsConditionalThe account number of the payee bank account. Required when payeeInvoice set to true.
accountHolderstringConditionalThe account name of the payee bank account. Required when payeeInvoice set to true.

WCQ Invoice Parameters

FieldFormatRequired?Description
billerAccountNumberstringMandatoryThe account number issued by WCQ for this biller.

Claims Parameters

FieldFormatRequired?Description
billerClaimIdStringConditionalInvoice line item identifier from the PMS. This field should be unique for each claim on each invoice.
This is strongly recommended so you can explicitly match the claimId we issue you with your claim ID in your system as arrays of claims may be out of order compared to the original submission order.
providerProviderConditionalProvider is the entity (person/organisation) who performed the work. Required by some Programs.
itemPublisherstringconditionalThe entity that has responsibility for the item code. Could be defaulted by PMS in specific sectors. Example values include: fred, pbs, mims, ndis, tac.
itemCodestringMandatoryThe unique identifier for the service or good.
descriptionstringConditionalDescription of the item or service.
itemCustomFieldsItemCustomFieldsConditionalAdditional service details, as required for some programs.
patientPatientConditionalIf the patient receiving the service is different to the member (e.g. Parent/Child). Required by some programs.
serviceDatedate
YYYY-MM-DD
ConditionalThe date that the service was performed in date format. Required if serviceDateTime or servicePeriod is not provided.
serviceDateTimedateTime
YYYY-MM-DDTHH:mm:ss.sss±HH:mm
ConditionalThe date and time that the service was performed in dateTime format. Required if serviceDate or servicePeriod is not provided.
servicePeriodPeriodConditionalThe start and end date and time that the service was performed in dateTime format. Required if serviceDate or serviceDateTime is not provided.
locationLocationConditionalLocation where the service occurs.
consentReceivedbooleanConditionalClient/patient consent has been granted.
consentAuthoritystringConditionalThe party who has the consent record.
quantitydecimal (4 dp)ConditionalNote: the unit of measure is defined by the program for each item. 4 dp is required to allow quantity * price to equal a specific total.
Note that for Medicare Easyclaim transactions, the quantity for each claim line is always one.
unitPricedecimal (4 dp)ConditionalThe price for each unit of the product or service. This price is tax inclusive when tax is applicable.
Note that for Medicare Easyclaim transactions, the quantity for each claim line is always one, so the unit price must reflect this.
taxCodestringConditionalValues include:
GST (inclusive of 10% GST)
FRE (exclusive of 10% GST)
OOS (GST out of scope - e.g. international items).
Note: For NDIS claims with “P5” tax code, use OOS.
contractNumberstringConditionalThe contract that this claim is claimed against.
contractLineItemNumberstringConditionalThe 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.

FieldFormatRequired?Description
personPersonConditionalThe details of a person Provider. Required when the Provider is a person.
organizationOrganizationConditionalThe details of an organization Provider. Required when the Provider is an organization.
registrationsRegistrationsConditionalAny registrations that the provider has.
contactPointContactPointConditionalContact options for this provider and their respective numbers/values.
disciplinestringConditionalThe 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.
Example values can be seen here Provider Disciplines.

Person Parameters

FieldFormatRequired?Description
givenNamestringConditionalThe given name of the Provider.
familyNamestringConditionalThe family name of the Provider.

Organization Parameters

FieldFormatRequired?Description
facilityNamestringMandatoryThe name of the organisation facility that provided the service. Eg. the name of a gym or sports complex.

Registrations Parameters

FieldFormatRequired?Description
ahpraRegistrationNumberstringConditionalThe AHPRA number of the provider.
medicareProviderNumberstringConditionalThe Medicare number of the provider.
medibankProviderNumberstringConditionalThe Medibank number of the provider.
worksafevicProviderNumberstringConditionalThe Worksafe Victoria number of the provider.
pbsPharmacyApprovalNumberstringConditionalThe PBS Pharmacy Approval number of the provider.
workCoverQldProviderNumberstringConditionalThe Work Cover QLD number of the provider.
hbfProviderNumberstringConditionalThe HBF Number of the provider.
siraProviderNumberstringConditionalThe Sira Number of the provider.

ContactPoint Parameters

FieldFormatRequired?Description
phonestringConditionalThe provider’s phone number.
emailstringConditionalThe provider’s email address.
remittanceEmailstringConditionalThe email address that the provider wants remittances sent to.
mobilestringConditionalThe provider’s mobile number.
otherstringConditionalAny 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.

FieldFormatRequiredDescription
ndisNDISConditionalThis field is conditional for NDIS API Managed claims.
medicareMedicareConditionalThis field is conditional for Medicare claims.
generalMedicalGeneral MedicalConditionalThis field is conditional for general medical claims.
pharmacyPharmacyConditionalThis field is conditional for pharmacy claims.
ambulanceAmbulanceConditionalThis field is conditional for ambulance claims.
pathologistPathologistConditionalThis field is conditional for pathology claims.
radiologistRadiologistConditionalThis field is conditional for radiology claims.
dentalDentalConditionalThis field is conditional for dental claims.
uomUOMConditionalThis field is optional and can be filled up when the item code has a non-standard Unit of Meassure (kilometers

UOM Parameters

FieldFormatRequired?Description
amountdecimal (2dp)ConditionalThe item total amount. It can be entered if item code UOM is: kilometers or minutes.

NDIS Parameters

FieldFormatRequired?Description
serviceBookingNumberintegerConditionalThis field is required for API claims. Maximum 10 digits.
abn11 digits ABNConditionalThis 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.
exemptionReasonValid NDIS exemption mnemonicConditionalThis 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.
claimTypestring
(4 chars)
ConditionalThis 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.
cancellationReasonstring
(4 chars)
ConditionalIf 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:

ValueDescription
11 digit ABNA 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
REIMBParticipant 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.
EXCLSATO 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

FieldFormatRequired?Description
distanceintegerConditionalThe 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
duplicateServiceOverridebooleanConditionalSet to true if it is known that an MBS item number has been correctly applied to the same patient twice in a single day.
For example, a GP attending the same patient for the same MBS item number on a single day or bilateral X-rays that use the same MBS item numbers for left and right images performed on the same day.
afterCareOverridebooleanConditionalSet to true to indicate that a service is not normal aftercare (i.e. treated for an unrelated condition or for complications form the operation)
lspNumberstringConditionalThe Location Specific Practice Number. Required for Medicare Easyclaim invoices when the patient service is listed in the Diagnostic Imaging Services Table (DIST) or Group T2 Radiation Oncology services in the General Medical Services Table (GMST). LSPN is 6 digits.
equipmentIdstringConditionalThe equipment ID required for certain Medicare Easyclaim invoices. Equipment ID is up to 5 characters.
selfDeemedCodestringConditionalThe self-deemed code is required for certain Medicare Easyclaim diagnostic or pathology invoices. When this code is provided, you cannot set referral/request details. Valid values are:
SD - self-deemed is a service provided by a consultant physician or specialist as an additional service to a valid request
SS - substituted service is a service provided that has replaced the original service requested
N - not self-deemed
specimenCollectionPointIdstringConditionalRequired for Medicare Easyclaim Bulkbill pathology invoices only. Length up to 4 characters.
amountPaidByClientdecimal (2dp)ConditionalUse this field to indicate how much was paid by the client for this line item. If isFullyPaidByClient is set to true at the invoice level, this field at the claim line-item level is ignored.

General Medical Parameters

FieldFormatRequired?Description
numberOfPatientsintegerConditionalThe number of patients associated with the claim.

Pharmacy Parameters

FieldFormatRequired?Description
scriptNumberstringConditionalThe script number of the item.
prescribingDoctorNumberstringConditionalThe doctor number of the doctor who prescribed the item, as stated on the script.
prescribingDoctorNamestringConditionalThe name of the doctor who prescribed the item, as stated on the script.
itemsDispensedstringConditionalThe number of individual items (e.g. pills) dispensed if a part-pack.
isScriptPrivatebooleanConditionalA true/false identifier as to whether the script is a private script.

Ambulance Parameters

FieldFormatRequired?Description
pickUpDateTimedateTime
YYYY-MM-DDTHH:mm:ss.sss±HH:mm
OptionalThe start date and time of the ambulance journey
pickUpAddressLine1stringOptionalThe first line of the pick up address
pickUpAddressLine2stringOptionalThe second line of the pick up address
pickUpCitystringOptionalThe city/suburb of the pick up location
pickUpPostalCodestringOptionalThe post code of the pick up location
pickUpStatestringOptionalThe state of the pick up location, e.g. "NSW", "VIC"
dropOffDateTimedateTime
YYYY-MM-DDTHH:mm:ss.sss±HH:mm
OptionalThe end date and time of the ambulance journey
dropOffAddressLine1stringOptionalThe first line of the drop off address
dropOffAddressLine2stringOptionalThe second line of the drop off address
dropOffCitystringOptionalThe city/suburb of the drop off location
dropOffPostalCodestringOptionalThe post code of the drop off location
dropOffStatestringOptionalThe state of the drop off location, e.g. "NSW", "VIC"
kmsstringOptionalThe distance travelled in kilometres

Pathologist Parameters

FieldFormatRequired?Description
prescribingDoctorNumberstringConditionalThe doctor number of the doctor who prescribed/referred the service.
prescribingDoctorNamestringConditionalThe name of the doctor who prescribed/referred the service.

Radiologist Parameters

FieldFormatRequired?Description
prescribingDoctorNumberstringConditionalThe doctor number of the doctor who prescribed/referred the service.
prescribingDoctorNamestringConditionalThe name of the doctor who prescribed/referred the service.

Dental Parameters

FieldFormatRequired?Description
jawstringConditionalIdentifies if the dental service relates to the upper or lower jaw. Valid values: upper or lower.
numberOfTeethintegerConditionalNumber of teeth.
toothNumberintegerConditionalIdentifies 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 at 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.

FieldFormatRequired?Description
memberNumberstringMandatoryMember’s identifier, as issued by the Program.
givenNamestringConditionalThe patient’s first name.
Note: Where a patient has only one name, that name should be entered into the familyName field and the word Onlyname be entered in the givenName field.
familyNamestringConditionalThe patient’s last name.
birthDatedate
YYYY-MM-DD
ConditionalThe patient’s date of birth.
genderstringConditionalValues include: male, female and unspecified.
patientCustomFieldsPatientCustomFieldsConditionalOther 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 at the invoice level.

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

FieldFormatRequired?Description
personIdentifierstringConditionalThis 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

FieldFormatRequired?Description
startdateTime
YYYY-MM-DDTHH:mm:ss.SSS±HH:mm
MandatoryStart date time of the service.
enddateTime
YYYY-MM-DDTHH:mm:ss.SSS±HH:mm
MandatoryEnd date time of the service.

Location Parameters

FieldFormatRequired?Description
addressAddressConditionalThe address where the service occurred.
positionPositionConditionalThe GPS position (WGS84) where the service occurred.
typestringconditionalRequired 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

FieldFormatRequired?Description
linesArray of stringsMandatoryEach line of the street address is a separate string.
citystringMandatoryThe city that the service occurred in.
postalCodestringMandatoryThe post code that the service occurred in.
statestringMandatoryThe state that the service occurred in.
countrystringConditionalThe country that the service occurred in.

Position Parameters

FieldFormatRequired?Description
longitudedecimalMandatoryWGS84 longitude
latitudedecimalMandatoryWGS84 latitude
altitudedecimalMandatoryWGS84 altitude

Example Submit Invoice Request - TAC

{
    "program": "tac",
    "responsePriority": "normal",
    "created": "2023-05-29T00:48:04+00:00",
    "invoiceNumber": "20230529747",
    "invoiceDate": "2023-05-29",
    "member": {
        "memberNumber": "12/81958",
        "givenName": "somefirstname",
        "familyName": "somelastname",
        "birthDate": "1962-09-18"
    },
    "claims": [
        {
            "serviceDate": "2023-05-29",
            "billerClaimId": "37cadedc-22e6-4522-a8b1-7cfc4ae321ae",
            "provider": {
                "person": {
                    "givenName": "somefirstname",
                    "familyName": "somelastname"
                },
                "registrations": {
                    "ahpraRegistrationNumber": "PHY0001234567",
                    "medicareProviderNumber": "1234567F"
                },
                "discipline": "physiotherapist"
            },
            "itemPublisher": "TAC",
            "itemCode": "PH602G",
            "quantity": 1,
            "unitPrice": 35.76,
            "description": "PHYSIO/HYDROTHERAPY: GROUP CONSULTATION"
        }
    ]
}

Example Submit Invoice Request - WSV

{
    "program": "wsv",
    "responsePriority": "normal",
    "created": "2023-05-29T00:54:28+00:00",
    "invoiceNumber": "ABC123",
    "invoiceDate": "2023-05-28",
    "member": {
        "memberNumber": "09110111111",
        "givenName": "somefirstname",
        "familyName": "somelastname",
        "birthDate": "1966-04-04"
    },
    "claims": [
        {
            "serviceDate": "2023-05-28",
            "billerClaimId": "54b0b585-16a8-4745-ad3b-18faf06f945a",
            "provider": {
                "person": {
                    "givenName": "somefirstname",
                    "familyName": "somelastname"
                },
                "registrations": {
                    "medicareProviderNumber": "123456AA"
                },
                "discipline": "doctor"
            },
            "itemPublisher": "MBS",
            "itemCode": "5040",
            "itemCustomFields": {
                "generalMedical": {
                    "numberOfPatients": 1
                }
            },
            "quantity": 1,
            "unitPrice": 158.83,
            "description": "Professional attendance by a general practitioner"
        }
    ]
}

Example Submit Invoice Request - NIB

{
    "program": "nib",
    "responsePriority": "normal",
    "created": "2023-05-24T06:22:08+00:00",
    "invoiceNumber": "20230524181",
    "invoiceDate": "2023-05-24",
    "member": {
        "memberNumber": "12345678",
        "givenName": "somefirstname",
        "familyName": "somelastname",
        "birthDate": "1993-07-29",
        "memberCustomFields": {
            "personIdentifier": "1"
        }
    },
    "claims": [
        {
            "serviceDate": "2023-05-24",
            "billerClaimId": "d1de737c-1b97-4389-ac4f-e228237f504d",
            "provider": {
                "person": {
                    "givenName": "somefirstname",
                    "familyName": "somelastname"
                },
                "registrations": {
                    "medicareProviderNumber": "1234567T"
                },
                "discipline": "doctor"
            },
            "itemPublisher": "mbs",
            "itemCode": "23",
            "quantity": 1,
            "unitPrice": 39.75,
            "description": "Professional attendance by a general practitioner at consulting rooms (other than a service to which another item in the table applies) lasting less than 20 minutes and including any of the following that are clinically relevant: (a) taking a patient history; (b) performing a clinical examination; (c) arranging any necessary investigation; (d) implementing a management plan; (e) providing appropriate preventive health care; for one or more health-related issues with appropriate documentation-each attendance"
        }
    ]
}

Example Submit Invoice Request - WCQ

{
    "billerInvoiceId": "a396a502-3ce5-4e73-9127-3cdc4a2d94d1",
    "program": "wcq",
    "responsePriority": "normal",
    "created": "2023-05-29T10:00:00+00:00",
    "invoiceNumber": "123456789",
    "invoiceDate": "2023-05-29",
    "invoiceCustomFields": {
        "wcq": {
            "billerAccountNumber": "P0001234567"
        }
    },
    "member": {
        "memberNumber": "S11DM001111",
        "givenName": "somefirstname",
        "familyName": "somelastname",
        "birthDate": "1997-06-10",
        "gender": "male",
        "email": "someemail@yahoo.com"
    },
    "claims": [
        {
            "billerClaimId": "038444af-64b9-46ed-8a1a-fe837996af75",
            "provider": {
                "person": {
                    "givenName": "somefirstname",
                    "familyName": "somelastname"
                },
                "registrations": {
                    "medicareProviderNumber": "1234567A"
                },
                "contactPoint": {
                    "email": "someemail@somedomain.com.au"
                },
                "discipline": "physiotherapist"
            },
            "itemPublisher": "wcq",
            "itemCode": "100006",
            "serviceDate": "2023-05-29",
            "location": {
                "address": {
                    "lines": [
                        "some building name line 1",
                        "some unit line 2",
                        "some street address line 3"
                    ],
                    "city": "Sydney",
                    "postalCode": "2000",
                    "state": "NSW"
                }
            },
            "quantity": "1",
            "unitPrice": "88.00",
            "taxCode": "FRE",
            "description": "Workcover - Followup consultation"
        }
    ]
}

Example Submit Invoice Request - Medicare-PCI

{
    "billerInvoiceId": "d1de737c-1b97-4389-ac4f-e228237f504d",
    "program": "medicare-pci",
    "responsePriority": "normal",
    "created": "2023-05-29T01:12:10.793+00:00",
    "invoiceNumber": "123456789",
    "invoiceDate": "2023-05-29",
    "member": {
        "memberNumber": "1234567890",
        "givenName": "somefirstname",
        "familyName": "somelastname",
        "birthDate": "1976-05-06",
        "email": "something@email.com",
        "memberCustomFields": {
            "personIdentifier": "1"
        }
    },
    "invoiceCustomFields": {
        "referral": {
            "issueDate": "2023-03-13",
            "periodType": "S",
            "period": null,
            "referralProvider": {
                "providerNumber": "1234567F",
                "providerType": "S"
            }
        },
        "medicare": {
            "isFullyPaidByClient": true
        }        
    },
    "claims": [
        {
            "billerClaimId": "a396a502-3ce5-4e73-9127-3cdc4a2d94d1",
            "provider": {
                "person": {
                    "givenName": "somefirstname",
                    "familyName": "somelastname"
                },
                "registrations": {
                    "medicareProviderNumber": "1234567A"
                },
                "discipline": "Physiotherapist"
            },
            "itemPublisher": "MBS",
            "itemCode": "10960",
            "serviceDate": "2023-05-29",
            "serviceDateTime": "2023-05-29T01:00:00+00:00",
            "location": {
                "type": "R"
            },
            "quantity": 1,
            "unitPrice": 85,
            "taxCode": "FRE",
            "description": "STANDARD CONS 10960"
        }
    ]
}

Example Submit Invoice Request - Medicare-Bulkbill

{
    "billerInvoiceId": "e3190c24-a996-42a5-885d-c784b2a3ac09",
    "program": "medicare-bulkbill",
    "responsePriority": "normal",
    "created": "2023-05-26T06:54:25.218+00:00",
    "invoiceNumber": "123456789",
    "invoiceDate": "2023-05-26",
    "member": {
        "memberNumber": "1234567890",
        "givenName": "somefirstname",
        "familyName": "somelastname",
        "birthDate": "1961-04-07",
        "gender": "female",
        "email": "someemail@gmail.com",
        "memberCustomFields": {
            "personIdentifier": "1"
        }
    },
    "invoiceCustomFields": {
        "medicare": {
            "payeeProviderNumber": "1234567H"
        },
        "referral": {
            "issueDate": "2023-05-17",
            "periodType": "S",
            "period": null,
            "referralProvider": {
                "providerNumber": "1234567W",
                "providerType": "S"
            }
        }
    },
    "claims": [
        {
            "billerClaimId": "384494ba-ee7b-4ea0-978f-e1e5a4edbc03",
            "provider": {
                "person": {
                    "givenName": "somefirstname",
                    "familyName": "somelastname"
                },
                "registrations": {
                    "medicareProviderNumber": "1234567Y"
                },
                "discipline": "Medical Non-GP/Specialist"
            },
            "itemPublisher": "MBS",
            "itemCode": "47595",
            "serviceDate": "2023-05-24",
            "location": {
                "type": "R"
            },
            "consentReceived": true,
            "consentAuthority": "Medical Practice",
            "quantity": 1,
            "unitPrice": 72.4,
            "taxCode": "FRE",
            "description": "Procedures - Treatment of fracture of an"
        }
    ]
}

Example Submit Invoice Request - Medicare-DVA

{
    "billerInvoiceId": "45aa6c91-27f9-4035-a168-bf4183a7a827",
    "program": "medicare-dva",
    "responsePriority": "normal",
    "created": "2023-05-29T01:03:23.705+00:00",
    "invoiceNumber": "123456789",
    "invoiceDate": "2023-05-29",
    "member": {
        "memberNumber": "QSM12345",
        "givenName": "somefirstname",
        "familyName": "somelastname",
        "birthDate": "1977-06-12",
        "gender": "male"
    },
    "invoiceCustomFields": {
        "medicare": {
            "payeeProviderNumber": "123456RK"
        },
        "referral": {
            "issueDate": "2022-08-22",
            "periodType": "S",
            "referralProvider": {
                "providerNumber": "1234567F",
                "providerType": "S"
            }
        },
        "medicareDva": {
            "disability": {
                "isRelated": false
            }
        }
    },
    "claims": [
        {
            "billerClaimId": "00777747-6416-4ace-a635-dc4f8b70e1cb",
            "provider": {
                "person": {
                    "givenName": "somefirstname",
                    "familyName": "somelastname"
                },
                "registrations": {
                    "medicareProviderNumber": "1234567Y"
                },
                "discipline": "Podiatrist"
            },
            "itemPublisher": "DVA",
            "itemCode": "F012",
            "serviceDate": "2023-05-29",
            "location": {
                "address": null,
                "position": null,
                "type": "R"
            },
            "consentReceived": true,
            "consentAuthority": "Medical Practice",
            "quantity": 1,
            "unitPrice": 85.65,
            "taxCode": "FRE",
            "description": "Subsequent Consultation"
        }
    ]
}

Example Submit Invoice Request - Medicare-Easyclaim-PC

{
	"billerInvoiceId": "b1f5b300-63de-4f01-ac3c-af0b848b3fc7",
	"program": "medicare-easyclaim-pc",
	"responsePriority": "normal",
	"created": "2023-01-30T03:49:25.548+00:00",
	"invoiceNumber": "123456",
	"invoiceDate": "2023-01-30",
	"member": {
		"memberNumber": "1234567",
		"memberCustomFields": {
			"personIdentifier": "01"
		}
	},
    "invoiceCustomFields": {
        "medicare": {
            "isFullyPaidByClient": false
        }        
    },
	"claims": [
		{
			"billerClaimId": "bbb1bc07-287a-4802-ae68-0a0bfb9969f7",
			"provider": {
				"registrations": {
					"medicareProviderNumber": "1234567K"
				},
				"discipline": "doctor"
			},
			"itemPublisher": "mbs",
			"itemCode": "23",
			"serviceDate": "2023-01-30",
			"quantity": 1,
			"unitPrice": 80,
			"itemCustomFields": {
				"medicare": {
					"duplicateServiceOverride": "false",
					"afterCareOverride": false,
					"lspNumber": null,
					"equipementId": null,
					"selfDeemedCode": null,
					"amountPaidByClient": 60,
					"specimenCollectionPointId": null
				}
			},
			"description": "standard surgery consultation"
		}
	]
}

Example Submit Invoice Response - Generic

Note: this response is synchronous

{
  "invoiceId": "72f5dca0-be8a-4469-b349-25a4e2cc9463",
  "claims": [
    {
      "claimId": "8f637f02-6ed7-44f4-af2f-ad9106487190",
      "billerClaimId": "bbb1bc07-287a-4802-ae68-0a0bfb9969f7"
    }
  ]
}

Cancel Invoice

POST /invoices/{invoiceId}/cancel

The provider can request a cancellation of an invoice at any time, but it is up to the program whether they accept or reject the request to cancel the invoice. Once the cancellation request has been processed by the program, the Invoice Claiming Status Updated webhook will trigger.

If the cancellation request is accepted, the invoice’s claims will be updated with cancelled status, however if the cancellation request is not accepted the invoice’s claims will be reverted back to their previous states. The program may also pass a message back as to why they did or did not accept the cancellation request.

Path Parameters

FieldFormatRequired?Description
invoiceIdUUIDMandatoryThe reference of the invoice to be cancelled

Body Parameters

FieldFormatRequired?Description
invoiceIdUUIDMandatoryHICAPS’s unique reference of the invoice. This is the invoiceId of the invoice to be cancelled by the user.
reasonstringConditionalA reason why the invoice is to be cancelled.

Example Cancel Invoice Request

{
  "invoiceId" : "1194e7aa-04f6-4b76-96ea-70e69791eccf",
  "reason" : "The invoice was submitted by mistake."
}

Invoice Claiming Status Updated

WEBHOOK → {onInvoiceClaimingStatusUpdated}

This webhook will trigger when the program provides an adjudication update to HICAPS for this invoice. Each invoice may receive one or many Invoice Claiming Status Updated webhooks depending on the scenario, however most invoices will receive just one with all adjudication results received from the program in the single webhook.

Path Parameters

FieldFormatRequired?Description
{onInvoiceClaimingStatusUpdated}URIMandatoryThe URI that you provided during onboarding for the claiming.invoice.updated event.

Webhook Body Parameters

FieldDescription
idA unique ID per event.
createdThe date and time of the event in Unix Epoch Time format.
dataSchema follows the structure of a Claiming Status Update
typeclaiming.invoice.updated
_linkslp:webhook-error defines the URI to POST in case the webhook needs to be replayed by HICAPS.
Note: this value can be null or empty if no replay is possible. See example webhook.

Claiming Status Update Parameters

FieldFormatRequired?Description
invoiceIdUUIDMandatoryHICAPS’s reference for the invoice.
stateenumConditionalThe state of the invoice as determined by the program. Values include: provisionallyApproved, approved, rejected, cancelPending, etc. These values are described in the Claim State table.
Note: this is an invoice-level state which is only used by some funds and in some circumstances and so may not be provided (if none provided check claimStatuses array for individual claim states.)
claimStatusesArray of ClaimStatusesMandatoryAn array of responses to the claims (line items) on the invoice.
invalidParamsArray of Invalid ParametersConditionalAn array of fields and their associated errors, at the invoice level. Where specified, this data may be used to highlight particular fields within claims which are leading to a rejection or lesser funding result.
actionsArray of ActionsConditionalAn optional list of actions the user can take if there are issues with the claim.

ClaimStatuses Parameters

FieldFormatRequired?Description
claimIdUUIDMandatoryHICAPS’s reference to this claim.
billerClaimIdStringConditionalInvoice line item identifier from the user’s application, eg. PMS.
programClaimIdStringConditionalThe Program’s identifier for the claim. For the NDIS this is the Payment Reference Number
benefitdecimalConditionalThe amount that will be paid by the program for this claim.
adjudicationsAn array of AdjudicationsConditionalThe 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 (benefit).
stateenumMandatoryThe state of the claim as determined by the program. Values include: provisionallyApproved, approved, rejected. These values are described in the Claim State table.
statusTitlestringConditionalDisplayed to the user as the status of the claim. Normally not required. Only required where the standard “state” would not effectively communicate the state to the user. See States, Statuses & Actions. Maximum of 20 chars.
statusDescriptionstringConditionalDisplayed to the user as the description for the claim.
invalidParamsArray of Invalid ParametersConditionalAn array of fields and their associated errors, at the claim level. Where specified, this data may be used to highlight particular fields within claims which are leading to a rejection or lesser funding result.

Adjudications Parameters

FieldFormatRequired?Description
reasonstringConditionalProvides a text description of the adjudication result. This is why the decision has been made. E.g. “Eligible amount”, “Bonus”, “Loyalty”, “Deductible”, “Eligible Percentage”
amountdecimalConditionalFormatted to two decimal places. Used where the category refers to a monetary amount. Eg. 20.00.
valuestringConditionalUsed where the category refers to a non-monetary amount. For example "70%".

Actions Parameters

The program may choose to respond to a claim with one or more actions for the Provider to take before the claim can be processed further by the Program.

See States, Statuses & Actions for more info.

FieldFormatRequired?Description
titlestringConditionalA short title for the action which may display as a tooltip.
descriptionstringConditionalA contextual description of the action required to be taken by the provider.
hrefURIConditionalA link, if applicable, the user can follow for more information or to complete the action.
classstringConditionalThe type of action this is, for example info or action

Example Invoice Status Updated Webhook - TAC

{
  "id": "d76eac52-6b7f-4303-8c70-91ae2f4313f9",
  "created": 1565140165,
  "data": {
    "invoiceId": "d5e6e8f7-bc9c-4a5b-8c60-8e8ffd665e26",
    "claimStatuses": [
      {
        "claimId": "4d01ce18-bb10-4390-af84-3a2c56e2dc44",
        "billerClaimId ": "1",
        "benefit": 120,
        "adjudications": [
          {
            "amount": 106,
            "reason": "Standard package"
          },
          {
            "amount": 14,
            "reason": "Bonus loyalty"
          }
        ],
        "state": "approved"
      },
      {
        "claimId": "4d01ce18-bb10-4390-af84-3a2c56e2dc44",
        "billerClaimId ": "2",
        "benefit": 0,
        "adjudications": [
          {
            "amount": 0,
            "reason": "Item not applicable for xxxxx..."
          }
        ],
        "state": "rejected"
      },
      {
        "claimId": "68e1a679-a455-4726-b52d-d467c7f2d1f5",
        "billerClaimId ": "3",
        "benefit": 24,
        "adjudications": [
          {
            "reason": "Paid at reduced rate: Contact TAC"
          }
        ],
        "state": "approved"
      }
    ]
  },
  "type": "claiming.invoice.updated",
  "_links": {
    "lp:webhook-error":
    {
      "href": null
    }
  }
}

Example Invoice Status Updated Webhook - NDIS API

{
    "id": "9bf90c41-7210-4222-a787-c5c2960824ec",
    "created": 1644217287,
    "data": {
        "invoiceId": "67f9120c-9b2d-4d32-9f09-06fbd600a1e8",
        "claimStatuses": [
            {
                "claimId": "a0ebe2b4-137b-4606-8c18-9989fda0155c",
                "billerClaimId": "CLM-ID-01",
                "state": "approved",
                "benefit": 47.21,
                "adjudications": [],
                "statusTitle": null,
                "statusDescription": null,
                "invalidParams": []
            },
            {
                "claimId": "da79e17e-a34b-4f57-8e05-da9ae18106f2",
                "billerClaimId": "01caeeb3-880e-4d83-8299-4bd480303ca3",
                "state": "rejected",
                "benefit": 0,
                "adjudications": [
                    {
                        "reason": "Maximum number of services for this item already paid",
                        "amount": null,
                        "value": null
                    }
                ],
                "statusTitle": null,
                "statusDescription": null,
                "invalidParams": []
            }
        ],
        "invalidParams": [],
        "actions": []
    },
    "type": "claiming.invoice.updated",
    "_links": {
        "lp:webhook-error": {
            "href": null
        }
    }
}

Invoice Payment Status Updated

WEBHOOK → {onInvoicePaymentStatusUpdated}

Once HICAPS receives adjudication responses for every claim on an invoice, the invoice is sent to the payment processor and assigned to a payment for that biller. All payments for a single biller for a single program are rolled up into a single payment at the next payment run. When this payment run occurs this webhook will trigger for every invoice in that payment.

This means there could be a large number of webhooks triggered when the payment batch triggers. For Example:

  • Biller ABC has processed 10 TAC invoices that day for a total value of $1200. All invoices are fully approved by TAC.
  • Biller ABC has also processed 3 Medibank invoices that day for a total value of $850. All invoices are fully approved by Medibank.

This means that at the next payment run, 13 payment.invoice.updated webhooks will trigger for this biller to their PMS.

Note that these payment webhooks will generally only trigger for payments made by HICAPS. Where the payment is made by a program (not by HICAPS) these webhooks may not trigger if the program does not tell us about the payment they made.

Path Parameters

FieldFormatRequired?Description
{onInvoicePaymentStatusUpdated}URIMandatoryThe URI that you provided during onboarding for the payment.invoice.updated event.

Webhook Body Parameters

FieldDescription
idA unique ID per event.
createdThe date and time of the event in Unix Epoch Time format.
dataSchema follows the structure of a Payment Status Update
typepayment.invoice.updated
_linkslp:webhook-error defines the URI to POST in case the webhook needs to be replayed by HICAPS.
Note: this value can be null or empty if no replay is possible. See example webhook.

Payment Status Update Parameters

FieldFormatRequired?Description
invoiceIdUUIDMandatoryHICAPS’s reference for the invoice.
paymentIdUUIDMandatoryLanternPay’s reference for the payment.
stateenumMandatoryThe state of the payment. Values include: sent, failed, held, overpaid
claimTransactionsArray of Claim TransactionsMandatoryAn array transactions for each claim on the invoice.

Claim Transactions Parameters

FieldFormatRequired?Description
claimIdUUIDMandatoryHICAPS’s reference to this claim.
amountdecimal (2 dp)MandatoryThe amount paid for the claim.

Example Invoice Payment Status Updated Webhook

{
    "id": "ac4ca65b-3c80-45a9-8fbd-88f8babe4137",
    "created": 1606963723,
    "data": {
        "invoiceId": "858ae1db-843e-461c-aab9-7dbaef7c83b6",
        "paymentId": "fdc0bf05-02c6-478b-8a35-3838317781f1",
        "state": "sent",
        "claimTransactions": [
            {
                "claimId": "ea070557-757d-4127-8be6-690cb05b948a",
                "amount": 234.23
            },
            {
                "claimId": "54eadf24-aaba-4dbd-8d3b-f15f01c0ad3f",
                "amount": 34.12
            }
        ]
    },
    "type": "payment.invoice.updated",
    "_links": {
        "lp:webhook-error": {
            "href": "https://lanternpay.com/sample/webhook/8ad735a2-21a0-481a-9174-205817e95110"
        }
    }
}

Predeterminations

Predeterminations enable the user to retrieve the expected funding result prior invoice submission. Where possible the program applies the same rules to respond to Predetermination requests. Predeterminations are used for information purpose only; they are not binding nor final.

Note: Not all programs support predeterminations, so any predeterminations sent for the below programs will be ignored and we recommend you disable predeterminations for these programs:

  • National Disability Insurance Scheme (ndis-agency)
  • Medicare (all medicare-... sub-types)
  • WorkCover Queensland (wcq)
  • icare: Insurance and Care NSW (icare)

This resource allows the submission of a predetermination to obtain a real-time result.

Submit Predetermination

POST /billers/{billerId}/predetermination

Path Parameters

FieldFormatRequired?Description
billerIdUUIDMandatoryHICAPS’s unique reference for the Biller.

Body Parameters

Schema follows the structure of an Invoice, as defined above.

Submit Predetermination Request

See examples above for Submit Invoice Request.

Predetermination Status Updated

WEBHOOK → {onPredeterminationStatusUpdated}

Path Parameters

FieldFormatRequired?Description
{onPredeterminationStatusUpdated}URIMandatoryThe URI that you provided for the onPredeterminationStatusUpdated event.

Webhook Body Parameters

FieldDescription
idA unique ID per event.
createdThe date and time of the event in Unix Epoch Time format.
typeclaiming.predetermination.updated
dataSchema follows the structure of a Claiming Status Update webhook (i.e. the same as the Invoice Updated webhook structure)
_linkslp:webhook-error defines the URI to POST in case the webhook needs to be replayed by HICAPS.
Note: this value can be null or empty if no replay is possible. See example webhook.

Example Predetermination Status Updated - NDIS

{
  "id": "d76eac52-6b7f-4303-8c70-91ae2f4313f9",
  "created": 1565140165,
  "data": {
    "invoiceId": "d5e6e8f7-bc9c-4a5b-8c60-8e8ffd665e26",
    "created": "2019-06-12T12:41:12:222",
    "claimStatuses": [
      {
        "claimId": "4d01ce18-bb10-4390-af84-3a2c56e2dc44",
        "billerClaimId ": "001",
        "benefit": 0.00,
        "adjudications": [
          {
            "amount": 0.00,
            "reason": "Your claim was rejected due to insufficient funding in your plan. Please contact the NDIS."
          }
        ],
        "state": "rejected"
      },
      {
        "claimId": "f17f52aa-e92b-4673-a749-bb4d7280f748",
        "billerClaimId ": "002",
        "benefit": 200.00,
        "adjudications": [
          {
            "amount": 150.00,
            "reason": "Standard Package"
          },
          {
            "amount": 50.00,
            "reason": "Bonus loyalty"
          }
        ],
        "state": "approved"
      },
      {
        "claimId": "f17f52aa-e92b-4673-4ae3-bb4d7280f748",
        "billerClaimId ": "003",
        "benefit": 24.00,
        "adjudications": [
          {
            "reason": "Paid at reduced rate. Please contact the NDIS."
          }
        ],
        "state": "approved"
      }
    ]
  },
  "type": "claiming.predetermination.updated",
  "_links": {
    "lp:webhook-error":
    {
      "href": null
    }
  }
}

Members

This resource allows various member actions, such as verification, to be performed.

Member Verification

POST /members/verify

The member verification API allows the biller to submit details collected about the Program member for verification by the fund.

Note: Currently member verification is supported by Medicare digital claim types only (i.e. medicare-bulkbill, medicare-dva, medicare-pci)

Member Verification Body Parameters

FieldFormatRequired?Description
memberMember ObjectMandatorySame structure as Member Parameters, including memberCustomFields
Note: Medicare requires the member’s Individual Reference Number (IRN) as shown on their card passed in the personIdentifier field.
programstringMandatoryThe program-specific code as described here.

Example Member Verification Request

{
    "member": {
        "memberNumber": "123413123",
        "givenName": "Genesis",
        "familyName": "Mason",
        "birthDate": "1990-04-01",
        "gender": "male",
        "email": "some-email@example.com",
        "memberCustomFields": {
            "personIdentifier": "1"
        }
    },
    "program": "medicare-bulkbill"
}

Example Member Verification Response

Note: this response is synchronous and you can use the memberVerificationRequestId to correlate to the asynchronous member verification webhook you will receive once verification completes.

{
    "memberVerificationRequestId": "abveac52-6b7f-4303-8c70-91ae2f431333"
}

Member Verification Updated

WEBHOOK → {onMemberVerificationUpdated}

This webhook will trigger with the member verification response from the program.

Path Parameters

FieldFormatRequired?Description
{onMemberVerificationUpdated}URIMandatoryThe URI that you provided for the onMemberVerificationUpdated event.

Webhook Body Parameters

FieldDescription
idA unique ID per event.
createdThe date and time of the event in Unix Epoch Time format.
typemember.verification.updated
datamemberVerificationRequestId is passed back so you can match this webhook to the original verification request.
status object follows the structure of Member Verification Status
member object follows the structure of Member Parameters, including memberCustomFields
_linkslp:webhook-error defines the URI to POST in case the webhook needs to be replayed by HICAPS.
Note: this value can be null or empty if no replay is possible. See example webhook.

Member Verification Status Parameters

FieldFormatRequired?Description
statestringConditionalThe current state of the member with the Program.
Either verified or unverified
statusTitlestringConditionalOptionally displayed to the user as the status of the member to provide a better label than just the state value.
statusDescriptionstringConditionalOptionally displayed to the user as the description for the status of the member - used to provide extra information/context.
programStatusCodestringConditionalThe status code provided by the program, if any. Refer to program’s documentation for information about specific status codes provided.
invalidParamsArray of Invalid ParametersConditionalAn array of fields and their associated errors. Where specified, this data may be used to highlight particular fields within the member data that the program has an issue with.

Example Member Verification Updated Webhook - Verified

{
    "id": "d76eac52-6b7f-4303-8c70-91ae2f4313f9",
    "created": 1565140165,
    "data": {
        "memberVerificationRequestId": "abveac52-6b7f-4303-8c70-91ae2f431333",
        "status": {
            "state": "verified",
            "statusTitle": null,
            "statusDescription": "Patient is eligible to claim for Medicare with details provided.",
            "programStatusCode": "0",
            "invalidParams": []
        },
        "member": {
            "memberNumber": "123413123",
            "givenName": "Genesis",
            "familyName": "Mason",
            "birthDate": "1990-04-01",
            "gender": "male",
            "email": "test@test.com",
            "memberCustomFields": {
                "personIdentifier": "1"
            }
        },
        "type": "member.verification.updated",
        "_links": {
            "lp:webhook-error": {
                "href": null
            }
        }
    }
}

Example Member Verification Updated Webhook - Unverified

{
    "id": "d76eac52-6b7f-4303-8c70-91ae2f4313f9",
    "created": 1565140165,
    "data": {
        "memberVerificationRequestId": "abveac52-6b7f-4303-8c70-91ae2f431333",
        "status": {
            "state": "unverified",
            "statusTitle": null,
            "statusDescription": "Patient Verification has been completed however patient details were not an exact match. Please check patient Medicare Card Number before claiming.",
            "programStatusCode": "8015",
            "invalidParams": []
        },
        "member": {
            "memberNumber": "123413123",
            "givenName": "Genesis",
            "familyName": "Mason",
            "birthDate": "1990-04-01",
            "gender": "male",
            "email": "test@test.com",
            "memberCustomFields": {
                "personIdentifier": "1"
            }
        },
        "type": "member.verification.updated",
        "_links": {
            "lp:webhook-error": {
                "href": null
            }
        }
    }
}

Items

This resources exposes the HICAPS hosted item libraries for all programs to be searched and retrieved. This allows for matching between non-program-supported and program-supported item codes.

For example, a pharmacy dispensary PMS may use AMT codes locally which the programs do not support and so any invoice submitted with an AMT code will be rejected by the program. Instead, this resource allows the service provider to search the item library of supported items, per program and discipline, for an equivalent item that the program does support which can be used in the invoice submission.

Note: the base URIs for the Items API functions are different to the Provider API base URIs, and are defined below:

EnvironmentURIDescription
Sandboxhttps://api.items.sandbox.lanternpay.comThis is a pre-production environment used for testing.
Productionhttps://api.items.lanternpay.comThis is the production environment.

POST /items/search

Note: this is a synchronous API, so no asynchronous webhook is triggered in this flow. Instead, the search results are shown in the synchronous response.

Item Search Request Body Parameters

FieldFormatRequired?Description
querystringMandatoryText string being searched. Must be minimum of 3 characters.
filtersItem FiltersMandatoryAn object of filters to apply to the search.
pageSizeintegerOptionalThe number of items returned per results page. Default is 50, maximum is 100.
offsetintegerOptionalThe starting record in the results page, with the first record on the first page being 0. Default is 0 (representing the first item on the first page).

Item Filters Parameters

FieldFormatRequired?Description
programstringMandatoryThe program’s items that are being searched. Valid program codes can be seen here.
disciplinestringMandatoryThe provider’s discipline. Valid disciplines can be seen here.
codestringOptionalThe item code if known. This can be used to confirm details/pricing of a known item, or you can insert the item code you know the item as which may assist the search accuracy.

Item Search Response Body Parameters

FieldFormatRequired?Description
itemsItemsMandatoryThe array of items in the search results.
pageInfoPage InfoMandatoryThe page info for the currently returned search page.

Items Parameters

FieldFormatRequired?Description
codestringMandatoryThe item code that the program knows the item by.
namestringMandatoryThe name of the item.
descriptionstringMandatoryThe description of the item, if included.
pricedecimal (2dp)MandatoryThe default item price, if included.
maxQuantitydecimal (2dp)OptionalMax Quantity of items allowed.
unitOfMeasurestringOptionalIndication if the item code is kilometers or minutes or null for standard behavior.
publisherstringMandatoryThe item publisher that the program knows the item by.

Page Info Parameters

FieldFormatRequired?Description
pageSizeintegerMandatoryThe page size as per the search request
offsetintegerMandatoryThe position of the first record in the search results page. E.g. if pageSize = 50 then offset will be 0, 51, 101, etc representing the first record in each results page.
totalintegerMandatoryThe total number of search results.

Example Item Search Request

{
    "query": "paracetamol 24mg liquid",
    "filters": {
        "program": "tac",
        "discipline": "pharmacy",
        "code": ""
    },
    "pageSize": 50,
    "offset": 0
}

Example Item Search Response

Note: this response is synchronous

{
    "items": [
        {
            "code": "1747Y",
            "name": "PARACETAMOL 24MG/ML ORAL LIQUID, 100ML",
            "description": null,
            "discipline": "pharmacy",
            "publisher": "CHM",
            "price": 20.95
        },
        {
            "code": "3348F",
            "name": "PARACETAMOL 24MG/ML ORAL LIQUID, 100ML",
            "description": null,
            "discipline": "pharmacy",
            "publisher": "CHM",
            "price": 20.95
        }
    ],
    "pageInfo": {
        "pageSize": 50,
        "offset": 0,
        "total": 2
    }
}

Terminals

This resource allows your application to interact with your HICAPS Terminal.

Note: the base URIs for the Terminals API functions are different to the Provider API base URIs, and are defined below:

EnvironmentURIDescription
Sandboxhttps://api.terminals.sandbox.lanternpay.comThis is a pre-production environment used for testing.
Productionhttps://api.terminals.lanternpay.comThis is the production environment.

Get Biller Details

GET /billers/{billerId}

This resource allows you to query the merchant details for a given biller (the API user) allowing you to verify the merchant information we hold for this biller.

It is critical that this merchant ID is visible and validated by the user as this detail will be sent to the terminal as part of all terminal transactions and must match what is configured on the terminal.

Path Parameters

FieldFormatRequired?Description
billerIdUUIDMandatoryHICAPS’s unique reference for the Biller.

Get Biller Details Response Parameters

FieldFormatRequired?Description
merchantIdstringMandatoryThe unique merchant ID for this merchant, as stored on the terminal. Can be null if no merchant details exist for this biller.
merchantNamestringMandatoryThe merchant name, as stored on the terminal. Can be null if no merchant details exist for this biller.

Example Get Biller Details Response

Note: this response is synchronous.

{
    "merchantId": "12345678",
    "merchantName": "Merchant Name"
}

Get Terminals

GET /billers/{billerId}/terminals

This resource allows you to retrieve a list of terminals that are online and eligible for this biller.

A biller may have multiple terminals associated with their merchant and on each terminal there may be zero to many provider numbers registered with that merchant ID on that terminal. The structure of the API response reflects this hierarchy.

Path Parameters

FieldFormatRequired?Description
billerIdUUIDMandatoryHICAPS’s unique reference for the Biller.

Query Parameters

FieldFormatRequired?Description
lastSeenInMinutesintegerOptionalAllows you to optionally specify a time range, in minutes, to filter the returned results by. Default is 180mins (if no query param is provided)

Get Terminals Response Parameters

FieldFormatRequired?Description
terminalsArray of TerminalsMandatoryArray of terminal objects found for this biller.

Terminals Parameters

FieldFormatRequired?Description
terminalIdstringMandatoryThe terminal’s ID, as stored on the terminal.
lastSeenAtdateTime
YYYY-MM-DDTHH:mm:ss.SSS±HH:mm
MandatoryThe date/time (and time zone) of when this terminal was last active.

Example Get Terminals Response

Note: this response is synchronous and can return an empty terminals array if no terminals are associated with this biller.

{
    "terminals": [
        {
            "terminalId": "12345A",
            "lastSeenAt": "2020-01-30T03:49:25.548+11:00"
        },
        {
            "terminalId": "54321A",
            "lastSeenAt": "2020-01-29T05:23:25.558+11:00"
        }
    ]
}

Get Terminal Details

GET /billers/{billerId}/terminals/{terminalId}

This resource allows you to retrieve additional details, including provider details, of a specific terminal.

Path Parameters

FieldFormatRequired?Description
billerIdUUIDMandatoryHICAPS’s unique reference for the Biller.
terminalIdstringMandatoryThe terminal’s ID, as stored on the terminal.

Get Terminal Details Response Parameters

FieldFormatRequired?Description
terminalIdstringMandatoryThe terminal’s ID, as stored on the terminal.
lastSeenAtdateTime
YYYY-MM-DDTHH:mm:ss.SSS±HH:mm
MandatoryThe date/time (and time zone) of when this terminal was last active.
providersArray of ProvidersOptionalArray of provider objects found for this merchant on this terminal. Can be null if no providers on this terminal.

Providers Parameters

FieldFormatRequired?Description
providerNumberstringMandatoryThe provider number for this provider, as stored on the terminal.
providerNamestringMandatoryThe provider name for this provider, as stored on the terminal.

Example Get Terminal Details Response

Note: this response is synchronous

{
    "terminalId": "44586X",
    "lastSeenAt": "2020-01-29T05:23:25.558+11:00",
    "providers": [
        {
            "providerNumber": "1234567Y",
            "providerName": "Provider Name A"
        },
        {
            "providerNumber": "1234567Z",
            "providerName": "Provider Name B"
        }
    ]
}

Submit Terminal Test

POST /billers/{billerId}/terminals/{terminalId}/test

This resource allows you to check if a terminal is online and connected.

Path Parameters

FieldFormatRequired?Description
billerIdUUIDMandatoryHICAPS’s unique reference for the Biller.
terminalIdstringMandatoryThe terminal’s ID, as stored on the terminal.

There is no body parameters for this request.

Example Terminal Test Response

Note: this response is synchronous.

This terminalProcessId is to be used to correlate terminal updates to the original API request.

{
    "terminalProcessId": "e63286a9-b155-4438-989e-a12020094663"
}

Terminal Test Completed

WEBHOOK → {onTerminalTestCompleted}

This webhook triggers once the terminal test has completed.

Path Parameters

FieldFormatRequired?Description
{onTerminalTestCompleted}URIMandatoryThe URI that you provided during onboarding for the terminal.test.completed event.

Webhook Body Parameters

FieldDescription
idA unique ID per event.
createdThe date and time of the event in Unix Epoch Time format.
dataA Terminal Test Completed object.
typeterminal.test.completed
_linkslp:webhook-error defines the URI to POST in case the webhook needs to be replayed by HICAPS. Note: this value can be null or empty if no replay is possible.

Terminal Test Completed Parameters

FieldFormatRequired?Description
terminalProcessIdstringMandatoryThe terminal process ID associated with this test, provided in the synchronous response to the Terminal Test request.
resultstringMandatoryThe result of the terminal test.

Example Terminal Test Completed Webhook

{
    "id": "0a2a42f5-30c9-4310-a6dc-1820067f3d18",
    "created": 1675729223,
    "data": {
        "terminalProcessId": "e63286a9-b155-4438-989e-a12020094663",
        "result": "ECR COMMS - OK"
    },
    "type": "terminal.test.completed",
    "links": {
        "lp:webhook-error": {
            "href": null
        }
    }
}

Submit Sale

POST /billers/{billerId}/terminals/{terminalId}/sales

This resource allows you to send a sale (i.e. a payment) to a nominated terminal.

Path Parameters

FieldFormatRequired?Description
billerIdUUIDMandatoryHICAPS’s unique reference for the Biller.
terminalIdstringMandatoryThe terminal’s ID, as stored on the terminal.

Sale Body Parameters

FieldFormatRequired?Description
amountdecimal (2dp)MandatoryThe total sale amount to be processed by the terminal.
invoiceIdstringOptionalIf this is a gap payment relating to a previously submitted invoice, the invoiceId should be passed in for reference.
computerNamestringOptionalThe Windows computer name identifier for the local workstation the PMS user is using to ensure optimal message routing.
cardNotPresentbooleanOptionalThis toggles the Select payment method screen to enable manual card entry on the terminal, by default this value will be false and the Select payment method will not be presented. Requires HicapsConnect 5.1.0.1 or greater.

Example Submit Sale Request

{
    "amount": 145.99,
    "invoiceId": "19c7034c-45c8-44ba-a815-7362ab1aa7b4",
    "computerName": "Reception01",
    "cardNotPresent": false
}

Example Submit Sale Response

Note: this response is synchronous.

This terminalProcessId is to be used to correlate terminal updates to the original API request.

{
    "terminalProcessId": "0c3fa7c6-46dd-456a-8dab-9de428b1ceb4"
}

Sale Completed

WEBHOOK → {onSaleCompleted}

This webhook triggers once a terminal sale has completed.

Path Parameters

FieldFormatRequired?Description
{onSaleCompleted}URIMandatoryThe URI that you provided during onboarding for the terminal.sale.completed event.

Webhook Body Parameters

FieldDescription
idA unique ID per event.
createdThe date and time of the event in Unix Epoch Time format.
dataA Sale Completed object.
typeterminal.sale.completed
_linkslp:webhook-error defines the URI to POST in case the webhook needs to be replayed by HICAPS. Note: this value can be null or empty if no replay is possible.

Sale Completed Parameters

FieldFormatRequired?Description
terminalProcessIdstringMandatoryThe terminal process ID associated with this sale, provided in the synchronous response to the Submit Sale request.
saleIdstringConditionalThe HICAPS reference for the sale.
saleReferencestringConditionalThe terminal’s reference for the sale.
transactionDateTimestring
YYYY-MM-DDTHH:mm:ss
ConditionalThe date/time stamp provided by the terminal for the transaction.
amountdecimal (2dp)ConditionalThe sub-total amount processed by the terminal, exclusive of any surcharge amount.
surchargedecimal (2dp)ConditionalThe surcharge amount added by the terminal, if applicable. If a surcharge was applied, this needs to be added to the recorded amount that the customer paid.
responseCodestringConditionalThe transaction status code received by the terminal from the merchant network. See Terminal Response Codes for more info.
responseTextstringConditionalThe transaction status description received by the terminal from the merchant network. See Terminal Response Codes for more info.

Example Sale Completed Webhook

{
    "id": "0a2a42f5-30c9-4310-a6dc-1820067f3d18",
    "created": 1675729223,
    "data": {
        "terminalProcessId": "bd78fa0d-89ef-4272-aea4-006603678459",
        "saleId": "4240a920-5eec-4e66-88c6-df35de6f92fa",
        "saleReference": "841198400720",
        "transactionDateTime": "2023-02-07T12:00:00",
        "amount": 39.1,
        "surcharge": 0,
        "responseCode": "08",
        "responseText": "APPROVED"
    },
    "type": "terminal.sale.completed",
    "links": {
        "lp:webhook-error": {
            "href": null
        }
    }
}

Submit Refund

POST /billers/{billerId}/terminals/{terminalId}/refunds

This resource allows you to send a refund to a nominated terminal.

Path Parameters

FieldFormatRequired?Description
billerIdUUIDMandatoryHICAPS’s unique reference for the Biller.
terminalIdstringMandatoryThe terminal’s ID, as stored on the terminal.

Refund Body Parameters

FieldFormatRequired?Description
amountdecimal (2dp)MandatoryThe refund amount.
saleIdstringOptionalIf this is a refund relating to a previously submitted sale, the saleId should be passed in for reference.
computerNamestringOptionalThe Windows computer name identifier for the local workstation the PMS user is using to ensure optimal message routing.
cardNotPresentbooleanOptionalThis toggles the Select payment method screen to enable manual card entry on the terminal, by default this value will be false and the Select payment method will not be presented. Requires HicapsConnect 5.1.0.1 or greater.

Example Submit Refund Request

{
    "amount": 21.50,
    "saleId": "19c7034c-45c8-44ba-a815-7362ab1aa7b4",
    "computerName": "Reception01",
    "cardNotPresent": false
}

Example Submit Refund Response

Note: this response is synchronous.

This terminalProcessId is to be used to correlate terminal updates to the original API request.

{
    "terminalProcessId": "0c3fa7c6-46dd-456a-8dab-9de428b1ceb4"
}

Refund Completed

WEBHOOK → {onRefundCompleted}

This webhook triggers once a terminal refund has completed.

Path Parameters

FieldFormatRequired?Description
{onRefundCompleted}URIMandatoryThe URI that you provided during onboarding for the terminal.refund.completed event.

Webhook Body Parameters

FieldDescription
idA unique ID per event.
createdThe date and time of the event in Unix Epoch Time format.
dataA Refund Completed object.
typeterminal.refund.completed
_linkslp:webhook-error defines the URI to POST in case the webhook needs to be replayed by HICAPS. Note: this value can be null or empty if no replay is possible.

Refund Completed Parameters

FieldFormatRequired?Description
terminalProcessIdstringMandatoryThe terminal process ID associated with this refund, provided in the synchronous response to the Submit Refund request.
refundIdstringConditionalThe HICAPS reference for the refund.
refundReferencestringConditionalThe terminal’s reference for the refund.
transactionDateTimestring
YYYY-MM-DDTHH:mm:ss
ConditionalThe date/time stamp provided by the terminal for the transaction.
amountdecimal (2dp)ConditionalThe total amount processed by the terminal.
surchargedecimal (2dp)ConditionalThe surcharge amount added by the terminal, if applicable.
Note: currently surcharging is not applicable for refund transactions, however scheme rules could change so it is encouraged to always parse this field, even though it’s expected to be 0 for refunds.
responseCodestringConditionalThe transaction status code received by the terminal from the merchant network. See Terminal Response Codes for more info.
responseTextstringConditionalThe transaction status description received by the terminal from the merchant network. See Terminal Response Codes for more info.

Example Refund Completed Webhook

{
    "id": "0a2a42f5-30c9-4310-a6dc-1820067f3d18",
    "created": 1675729223,
    "data": {
        "terminalProcessId": "0c3fa7c6-46dd-456a-8dab-9de428b1ceb4",
        "refundId": "4240a920-5eec-4e66-88c6-df35de6f92fa",
        "refundReference": "841198400720",
        "transactionDateTime": "2023-02-07T12:00:00",
        "amount": 39.1,
        "surcharge": 0,
        "responseCode": "08",
        "responseText": "APPROVED"
    },
    "type": "terminal.refund.completed",
    "links": {
        "lp:webhook-error": {
            "href": null
        }
    }
}

Terminal Screen Updated

WEBHOOK → {onTerminalScreenUpdated}

This webhook triggers whenever the terminal updates the content displayed on it’s screen. This stream of webhooks allows you to render/visualise the content shown on the terminal screen within your application as the user may not be able to see the terminal’s screen if it’s facing a customer.

Path Parameters

FieldFormatRequired?Description
{onTerminalScreenUpdated}URIMandatoryThe URI that you provided during onboarding for the terminal.screen.updated event.

Webhook Body Parameters

FieldDescription
idA unique ID per event.
createdThe date and time of the event in Unix Epoch Time format.
dataA Terminal Screen Updated object.
typeterminal.screen.updated
_linkslp:webhook-error defines the URI to POST in case the webhook needs to be replayed by HICAPS. Note: this value can be null or empty if no replay is possible.

Terminal Screen Updated Parameters

FieldFormatRequired?Description
terminalProcessIdstringMandatoryThe terminal process ID these screen updates relate to (i.e. a refund flow, or a sale flow, etc), provided in the synchronous response to the original request.
screenStatusScreen StatusMandatoryThe screen status object containing the on-screen message.

Screen Status Parameters

FieldFormatRequired?Description
messagestringMandatoryThe message currently being shown on the screen of the terminal.

Example Terminal Screen Updated Webhook

{
    "id": "021ea6fb-128b-49c2-b362-be26cc7be0ea",
    "created": 1678324989,
    "data": {
        "terminalProcessId": "d0599b64-eac5-444f-952a-53e8adc5e8da",
        "screenStatus": {
            "message": "TRANSACTION APPROVED"
        }
    },
    "type": "terminal.screen.updated",
    "links": {}
}

Terminal Response Codes

This section defines the common response codes received from the merchant processing systems. The terminal will provide these in response to sale, refund, etc. transactions.

Click to expand
Response CodeResponse Description
00Approved
01Refer to card issuer
02Refer to card issuer
03Invalid merchant
04Refer to card issuer
05Do not honour
06Transaction timeout
07Refer to card issuer
08Approved with signature
09Submitted for processing
12Declined
14Invalid card number
54Expired card
96System error
98MAC error
H1Timeout waiting for terminal
H2Timeout waiting for terminal
H3Timeout waiting for terminal
H6Terminal busy
BZTerminal busy
CEComms error
ENNetwork request error
HMHardware error
HWHardware error
LCLost carrier
NANetwork error
PFPower fail
TOTimeout
TCCancelled by user or input timeout

NDIS API Extensions

Base URIs

For NDIS API extensions, all URIs in this section are relative to these base URIs:

EnvironmentURIDescription
Sandboxhttps://api.ndis.providers.sandbox.lanternpay.comThis is a pre-production environment used for testing.
Productionhttps://api.ndis.providers.lanternpay.comThis is the production environment.

Item Category Mapping

This table shows the NDIS category mappings from the NDIS prefix to the technical and friendly names.

PrefixTechnical NameFriendly Names
01DAILY_ACTIVITIESDaily Activities
Assistance with daily life
Assistance with daily life (Includes SIL)
02TRANSPORTTransport
03CONSUMABLESConsumables
04SOCIAL_COMMUNITY_CIVICAssistance with social and community participation
Social Community and Civic Participation
Assistance with Social, Economic and Community Participation
05ASSISTIVE_TECHNOLOGYAssistive Technology
06HOME_MODIFICATIONSHome Modifications
Home Modifications and Specialised Disability Accommodation (SDA)
07SUPPORT_COORDINATIONSupport Coordination
Coordination of Supports
08CB_HOME_LIVINGCB Home Living
Improved Living Arrangements
09CB_SOCIAL_COMMUNITY_CIVICCB Social Community and Civic participants
Increased Social and Community Participation
10CB_EMPLOYMENTCB Employment
Finding and Keeping a Job
11CB_RELATIONSHIPSCB Relationships
Improved Relationships
12CB_HEALTH_WELLBEINGCB Health & Wellbeing
Improved Health and Wellbeing
13CB_LIFELONG_LEARNINGCB Lifelong learning
Improved Learning
14CB_CHOICE_CONTROLCB Choice & Control
Improved Life Choices
15CB_DAILY_ACTIVITYCB Daily Activity
Improved Daily Living Skills

NDIS Member Notifications

WEBHOOK → {ndisMemberNotification}

This section describes the various participant centric notifications that we can pass on to you for subscribed members. This is a generic notification that follows a standard structure. This standard structure can be used to communicate a number of generic participant notifications and may be expanded in the future to encompass other similar notifications as they are published by the NDIA. Note that this endpoint only covers participants enrolled in PACE.

Currently we support the following NDIS Member events:

  • BUDGET_UPDATED - This notification allows Plan Managers and Support Coordinator to be notified when a PACE participant’s budget is updated.
  • PLAN_APPROVED - This notification allows Plan Managers or Support Coordinator to be notified when a participant’s new plan is created.
  • RLTN_CREATED - This notification advises the registered provider that a new relationship has been created between the Participant and themselves.
  • RLTN_END_DATE_UPDATE - This notification advises the registered provider that the end date for the relationship has been updated. This may advise the end or extension of a relationship.

Path Parameters

FieldFormatRequired?Description
{ndisMemberNotification}URIMandatoryThe URL that you provided for the ndisMemberNotification event.

Webhook Body Parameters

FieldDescription
idA unique ID per event.
createdThe date and time of the event in Unix Epoch Time format.
dataA Ndis Member Notification object.
typendis.member.notification
_linkslp:webhook-error defines the URI to POST in case the webhook needs to be replayed by HICAPS. Note: this value can be null or empty if no replay is possible.

NDIS Member Notification

FieldFormatRequired?Description
eventIdstringMandatoryThis is the Event Id as passed through from the NDIA. Additional information on the different events and their schema can be found here.
responseNdis Member Response ObjectMandatoryA JSON object containing information pertinent to the event.

NDIS Member Response Object

The fields included in each event will differ depending on the event. Included fields have been document under NDIS Member Events

FieldFormatRequired?Description
participantintegerMandatoryThe participant’s NDIS number that the notification relates to. This will be present on all ndis.member.notification webhooks
providerRolestringConditionalThe role of the Provider e.g. Plan Manager or Support Coordinator
startDatedateConditionalThe start date of the event in YYYY-MM-DD format
endDatedateConditionalThe end date of the event in YYYY-MM-DD format

NDIS Member Events

Budget Updated

Description: This notification allows Plan Managers and Support Coordinator to be notified when a PACE participant’s budget is updated.

Trigger: The notification for this event will be triggered sent to the Plan Manager or Support Coordinator when a participant’s budget is updated via APIs or a Staff Member using the Staff Portal given that provider has consent/authority with the related participant.

The notification can take up to 1 hour to trigger.

Included Fields: This notification contains the following fields:

  • participant

Plan Approved

Description: This notification allows Plan Managers or Support Coordinator to be notified when a participant’s new plan is created.

Trigger: The notification for this event will be triggered and sent to the Plan Manager or Support Coordinator when there is a new plan approval given that the provider has consent/authority to view plan details with the related participant.

The notification can take up to 1 hour to trigger.

Included Fields: This notification contains the following fields:

  • participant

Relationship Created

Description: This notification advises the registered provider that a new relationship has been created between the Participant and themselves.

Trigger: The notification for this event will be triggered when:

  • My Provider Relationship is created between participant and provider in PACE.
  • Plan Manager Relationship is created between participant and provider in PACE.
  • Recovery Coach Relationship is created between participant and provider in PACE.
  • Support Coordinator Relationship is created between participant and provider in PACE.

Note: End Date can be blank if there is no end date recorded in the PACE system

The notification can take up to 1 hour to trigger.

Included Fields: This notification contains the following fields:

  • participant
  • providerRole
  • startDate
  • endDate

Relationship End Date Updated

Description: This notification advises the registered provider that the end date for the relationship has been updated. This may advise the end or extension of a relationship.

Trigger: The notification for this event will be triggered when:

  • My Provider Relationship end date is updated in PACE.
  • Plan Manager Relationship end date is updated in PACE.
  • Recovery Coach Relationship end date is updated in PACE.
  • Support Coordinator Relationship end date is updated in PACE.

The notification can take up to 1 hour to trigger.

Included Fields: This notification contains the following fields:

  • participant
  • providerRole
  • startDate
  • endDate

Example NDIS Member Webhook

{
    "id": "24c20488-549b-4af4-87f3-5bfd62c11ebf",
    "created": 1644278288,
    "data": {
        "eventId": "RLTN_END_DATE_UPDATE" ,
        "response": {
            "participant": 430111111,
            "providerRole": "Plan Manager",
            "startDate": "2023-12-30",
            "endDate": "2024-12-30"
        }
    },
    "type": "ndis.member.notification",
    "_links": {
        "lp:webhook-error": {
            "href": null
        }
    }
}

Plans

This section describes that Plan functions available through the NDIS API Extensions.

Retrieve Plan Type

POST /billers/{billerId}/members/{memberNumber}/plan/type/retrieve

This resource allows you to check if a participant has been migrated/enabled for PACE. NDIS’s transformation project. Calling this endpoint will return a true/false advising if the participant is PACE enabled or not.

Retrieve Plan Type Path Parameters

FieldFormatRequired?Description
billerIdUUIDMandatoryHICAPS’s unique reference for the Biller.
memberNumberstringMandatoryMember’s identifier, as issued by the NDIS. Max 10 digits.

Request Plan Type Body Parameters

FieldFormatRequired?Description
surnamestringMandatoryMember’s surname. Max 80 chars.
dateOfBirthstringMandatoryMember’s date of birth in YYYY-MM-DD format.

Example Retrieve a Plan Type Request

{
  "surname": "Rogers",
  "dateOfBirth": "2000-01-21"
}

Retrieve a Plan Type Response

HTTP 202

Plan Type Retrieved

WEBHOOK → {onPlanTypeRetrieved}

This webhook will trigger once the Plan has been retrieved.

Path Parameters

FieldFormatRequired?Description
{onPlanTypeRetrieved}URIMandatoryThe URL that you provided for the onPlanTypeRetrieved event.

Webhook Body Parameters

FieldDescription
idA unique ID per event.
createdThe date and time of the event in Unix Epoch Time format.
dataA PlanType object.
typendis.member.planType.retrieved
_linkslp:webhook-error defines the URI to POST in case the webhook needs to be replayed by HICAPS. Note: this value can be null or empty if no replay is possible.

Plan Type Parameters

FieldFormatDescription
isPacePlanbooleanReturns a true value if participant is PACE enabled. Returns false if empty.
planFirstStartDatedateThe plans first start date in YYYY-MM-DD format.

Example Plan Type Retrieved Webhook

{
    "id": "24c20488-549b-4af4-87f3-5bfd62c11ebf",
    "created": 1644278288,
    "data": {
        "isPacePlan": true,
        "planFirstStartDate": "2022-11-15"
    },
    "type": "ndis.member.planType.retrieved",
    "_links": {
        "lp:webhook-error": {
            "href": null
        }
    }
}

Retrieve a Plan

POST /billers/{billerId}/members/{memberNumber}/plans/retrieve

This resource allows for the retrieval of a participants approved plan details, for up to two plans. This includes the Plan ID, Plan Start Date and Plan End Date. This endpoint requires the participants NDIS Number, Surname and Date of Birth.

Path Parameters

FieldFormatRequired?Description
billerIdUUIDMandatoryHICAPS’s unique reference for the Biller.
memberNumberstringMandatoryMember’s identifier, as issued by the NDIS. Max 10 digits.

Request Plan Body Parameters

FieldFormatRequired?Description
memberNumberstringMandatoryMember’s identifier, as issued by the NDIS. Max 10 digits.
surnamestringMandatoryMember’s surname. Max 80 chars.
dateOfBirthstringMandatoryMember’s date of birth in YYYY-MM-DD format.

Example Retrieve a Plan Request

{
  "surname": "Rogers",
  "dateOfBirth": "2000-01-21"
}

Retrieve a Plan Response

HTTP 202

Plan Retrieved

WEBHOOK → {onPlanRetrieved}

This webhook will trigger once the Plan has been retrieved.

Path Parameters

FieldFormatRequired?Description
{onPlanRetrieved}URIMandatoryThe URL that you provided for the onPlanRetrieved event.

Webhook Body Parameters

FieldDescription
idA unique ID per event.
createdThe date and time of the event in Unix Epoch Time format.
dataAn array of Plans.
typendis.member.plans.retrieved
_linkslp:webhook-error defines the URI to POST in case the webhook needs to be replayed by HICAPS. Note: this value can be null or empty if no replay is possible.

Plan Parameters

FieldFormatDescription
participantPlanIdInteger maximum 10 charThe identifier for the plan, numeric, maximum 10 characters
planStartDatedateThe start date for the plan in YYYY-MM-DD format.
planEndDatedateThe end date for the plan in YYYY-MM-DD format.
isPacePlanbooleanReturns a true value if participant is PACE enabled. Returns false if empty.
planFirstStartDatedateThe plans first start date in YYYY-MM-DD format

Example Plan Retrieved Webhook

{
    "id": "24c20488-549b-4af4-87f3-5bfd62c11ebf",
    "created": 1644278288,
    "data": {
        "plans": [
            {
                "participantPlanId": 1080874,
                "isPacePlan": false,
                "planStartDate": "2020-12-09",
                "planEndDate": "2021-12-09"
            }
        ]
    },
    "type": "ndis.member.plans.retrieved",
    "_links": {
        "lp:webhook-error": {
            "href": null
        }
    }
}

Budgets

This section describes the API actions available to retrieve budgets for a participant

Retrieve Budgets

POST /billers/{billerId}/members/{memberNumber}/budgets/retrieve

This API will allow Plan Managers to retrieve a participant’s plan managed budget details for PACE enabled participants. New participant created in PACE should use NDIS number from PACE

In order to get a successful response, please ensure that as a Plan Manager, you have:

  • Received the participant’s consent to view their budget details , via the PACE System.

Note:

  • There will be different budget structures at Budget Type level
  • CORE will always be under flexible budget type
  • Capital & Capacity Building will always be under Stated budget type
  • Budget will be displayed as installment of Plan duration 3 Years

Path Parameters

FieldFormatRequired?Description
billerIdUUIDMandatoryHICAPS’s unique reference for the Biller.
memberNumberstringMandatoryMember’s identifier, as issued by the NDIS. Max 10 digits.

Retrieve Budgets Body Parameters

FieldFormatRequired?Description
surnamestringMandatoryMember’s surname. Max 80 chars.
dateOfBirthdateMandatoryMember’s date of birth in YYYY-MM-DD format.
planDatedateOptionalHistorical plan/budget date YYYY-MM-DD format (required to be between plan start and end date).

Retrieve Budgets Body Example

{
  "planId": 1080874,
  "surname": "Rogers",
  "dateOfBirth": "2000-01-21",
  "planDate": "2023-01-21"
}

Retrieve Budgets Response

HTTP 202

Budgets Retrieved

WEBHOOK → {onBudgetRetrieved}

This webhook will trigger once the Budgets for a plan have been retrieved

Path Parameters

FieldFormatRequired?Description
{onBudgetRetrieved}URIMandatoryThe URL that you provided for the onBudgetRetrieved event.

Webhook Body Parameters

FieldDescription
idA unique ID per event.
createdThe date and time of the event in Unix Epoch Time format.
dataProvides an array of Budget Information
typendis.member.budgets.retrieved
_linkslp:webhook-error defines the URI to POST in case the webhook needs to be replayed by HICAPS. Note: this value can be null or empty if no replay is possible.
lp:service-booking-updates-unsubscribe defines a templated URI to post to in order to unsubscribe from this member.

Budget Overview Parameters

FieldFormatDescription
planStartDatedateInstalment Start Date in YYYY-MM-DD format.
planEndDatedateInstalment End Date in YYYY-MM-DD format.
useFundingPeriodsstringMax Length (30). (e.g Funding Component)
releasedAmountdecimal (2dp)Released Amount under the plan. (e.g 150000.00). Max Length(P14, S2)
spentAmountdecimal (2dp)The total spent under the plan (e.g 1500.00). Max Length(P14, S2)
remainingAmountdecimal (2dp)The amount remanining under the plan (e.g 148500.00). Max Length(P14, S2)
approvedAmountdecimal (2dp)The total budget for the plan (e.g 150000.00). Max Length(P14, S2)
budgetTypeLevelDetailsAn Array of Budget Type ParametersAn Array of information detailing the budget at the budget type level

Budget Type Parameters

FieldFormatDescription
startDatedateInstalment Start Date in YYYY-MM-DD format.
endDatedateInstalment End Date in YYYY-MM-DD format.
releasedAmountdecimal (2dp)Released Amount under the budget type. (e.g 100000.00). Max Length(P14, S2)
approvedAmountdecimal (2dp)The total budget for the specific Support Category (e.g 100000.00). Max Length(P14, S2)
spentAmountdecimal (2dp)The total spent under the specific Support Category (e.g 1500.00). Max Length(P14, S2)
remainingAmountdecimal (2dp)The total remaining for the specific Support Category (e.g 98500.00). Max Length(P14, S2)
planManagementAn Array of Plan Management Budget ParametersAn Array of information detailing the budget at the plan management level

Plan Management Budget Parameters

FieldFormatDescription
startDatedateInstalment Start Date in YYYY-MM-DD format.
endDatedateInstalment End Date in YYYY-MM-DD format.
budgetStatusstringFor Agency Managed and Self-Managed (Budget Available/Budget Exhausted).
planManagementstringPlan Management type - Self,Plan or Agency. Max Length(30) e.g. ZCOR_PLAN
planManagementTextstringPlan Mangement Type Description. Max Length(1333) e.g. Core Plan Managed
approvedAmountdecimal (2dp)The total budget for support type. Max Length(P14, S2)
allocatedAmountdecimal (2dp)The amount allocated to the Support Type under Service Bookings. Max Length(P14, S2)
spentAmountdecimal (2dp)The amount spent under the support type. Max Length(P14, S2
remainingAmountdecimal (2dp)The amount remanining under the suport type. Max Length(P14, S2)
releasedAmountdecimal (2dp)The amount released under the suport type. Max Length(P14, S2).
supportTypeLevelDetailsAn Array of Support Type Budget ParametersAn Array of information detailing the budget at the support type level
fundingPeriodsAn Array of Funding Periods ParametersAn Array of information detailing the funding periods at the plan management budget level

Support Type Budget Parameters

FieldFormatDescription
startDatedateInstalment Start Date in YYYY-MM-DD format.
endDatedateInstalment End Date in YYYY-MM-DD format.
supportTypestringSupport Type Codes. Max Length(30) e.g. ZCOR
supportTypeTextstringSupport Type Description. Max Length(1333) e.g. Core
approvedAmountdecimal (2dp)The total budget for support type. Max Length(P14, S2)
allocatedAmountdecimal (2dp)The amount allocated to the Support Type under Service Bookings. Max Length(P14, S2)
spentAmountdecimal (2dp)The amount spent under the support type. Max Length(P14, S2
remainingAmountdecimal (2dp)The amount remanining under the suport type. Max Length(P14, S2)
releasedAmountdecimal (2dp)The amount released under the suport type. Max Length(P14, S2).
supportCategoryLevelDetailsAn Array of Support Category Budget ParametersAn Array of information detailing the budget at the category

Support Category Level Budget Parameters

FieldFormatDescription
startDatedateInstalment Start Date in YYYY-MM-DD format.
endDatedateInstalment End Date in YYYY-MM-DD format.
instalmentTypestringType of Installment (Regular/Once-off/Recurring).
budgetStatusstringFor Agency Managed and Self-Managed (Budget Available/Budget Exhausted).
fundingComponentNamestringFunding Component.
supportCategorystringSupport Category Code. Max Length(30) e.g. CONSUMABLES
supportCategoryTextstringSupport Category Description. Max Length(1333) e.g. Consumables
approvedAmountdecimal (2dp)The total budget for support type. Max Length(P14, S2)
allocatedAmountdecimal (2dp)The amount allocated to the Support Type under Service Bookings. Max Length(P14, S2)
spentAmountdecimal (2dp)The amount spent under the support type. Max Length(P14, S2
remainingAmountdecimal (2dp)The amount remanining under the suport type. Max Length(P14, S2)
releasedAmountdecimal (2dp)The amount released under the suport type. Max Length(P14, S2).
fundingPeriodsAn Array of Funding Periods ParametersAn Array of information detailing the funding periods at the support category level budget level

Funding Periods Parameters

FieldFormatDescription
startDatedateInstalment Start Date in YYYY-MM-DD format.
endDatedateInstalment End Date in YYYY-MM-DD format.
durationstringFunding period duration. Max Length(30). (example: 12 months)
amountdecimalFunding amount (example: 0)
releasedStatusstringReleased status. Max Length(30). (example: true)

Example Budget Retrieved Webhook

{
    "releasedAmount": 13000,
    "spentAmount": 0,
    "remainingAmount": 13000,
    "planStartDate": "2025-05-08",
    "planEndDate": "2026-05-07",
    "approvedAmount": 28000,
    "useFundingPeriods": "Funding component",
    "budgetTypeLevelDetails": [
        {
            "startDate": "2025-05-08",
            "endDate": "2026-05-07",
            "releasedAmount": 2500,
            "spentAmount": 0,
            "remainingAmount": 2500,
            "budgetTypeText": "Flexible",
            "approvedAmount": 10000,
            "planManagement": [
                {
                    "startDate": null,
                    "endDate": null,
                    "remainingAmount": 0,
                    "spentAmount": 0,
                    "releasedAmount": 0,
                    "approvedAmount": 0,
                    "nextInstalmentStartDate": null,
                    "nextInstalmentEndDate": null,
                    "nextInstalmentReleaseAmount": 0,
                    "instalmentStart": null,
                    "instalmentEnd": null,
                    "planManagementText": "Agency-managed",
                    "supportTypeLevelDetails": [
                        {
                            "startDate": null,
                            "endDate": null,
                            "releasedAmount": 0,
                            "remainingAmount": 0,
                            "approvedAmount": 0,
                            "spentAmount": 0,
                            "supportTypeText": "Core",
                            "supportCategoryLevelDetails": [
                                {
                                    "spentAmount": 0,
                                    "remainingAmount": 0,
                                    "nextInstalmentStartDate": null,
                                    "nextInstalmentEndDate": null,
                                    "nextInstalmentReleaseAmount": 0,
                                    "instalmentType": null,
                                    "instalmentStart": null,
                                    "instalmentEnd": null,
                                    "startDate": null,
                                    "endDate": null,
                                    "createdDate": null,
                                    "releasedAmount": 0,
                                    "approvedAmount": 0,
                                    "supportCategoryText": "Assistance with Daily Life",
                                    "supportCategory": null,
                                    "description": null,
                                    "fundingComponentName": "Core Flexible (Agency-managed)",
                                    "budgetStatus": "Budget available",
                                    "fundingPeriods": null
                                }
                            ]
                        }
                    ],
                    "fundingPeriods": null
                },
                {
                    "startDate": null,
                    "endDate": null,
                    "remainingAmount": 0,
                    "spentAmount": 0,
                    "releasedAmount": 0,
                    "approvedAmount": 0,
                    "nextInstalmentStartDate": null,
                    "nextInstalmentEndDate": null,
                    "nextInstalmentReleaseAmount": 0,
                    "instalmentStart": null,
                    "instalmentEnd": null,
                    "planManagementText": "Self-managed",
                    "supportTypeLevelDetails": [
                        {
                            "startDate": null,
                            "endDate": null,
                            "releasedAmount": 0,
                            "remainingAmount": 0,
                            "approvedAmount": 0,
                            "spentAmount": 0,
                            "supportTypeText": "Core",
                            "supportCategoryLevelDetails": [
                                {
                                    "spentAmount": 0,
                                    "remainingAmount": 0,
                                    "nextInstalmentStartDate": null,
                                    "nextInstalmentEndDate": null,
                                    "nextInstalmentReleaseAmount": 0,
                                    "instalmentType": null,
                                    "instalmentStart": null,
                                    "instalmentEnd": null,
                                    "startDate": null,
                                    "endDate": null,
                                    "createdDate": null,
                                    "releasedAmount": 0,
                                    "approvedAmount": 0,
                                    "supportCategoryText": "Assistance with Social, Economic and Community Participation",
                                    "supportCategory": null,
                                    "description": null,
                                    "fundingComponentName": "Core Flexible (Self-managed)",
                                    "budgetStatus": "Budget available",
                                    "fundingPeriods": null
                                }
                            ]
                        }
                    ],
                    "fundingPeriods": null
                },
                {
                    "startDate": "2025-05-08",
                    "endDate": "2026-05-07",
                    "remainingAmount": 2500,
                    "spentAmount": 0,
                    "releasedAmount": 2500,
                    "approvedAmount": 10000,
                    "nextInstalmentStartDate": "2025-08-08",
                    "nextInstalmentEndDate": "2025-11-07",
                    "nextInstalmentReleaseAmount": 2500,
                    "instalmentStart": "2025-05-08",
                    "instalmentEnd": "2025-08-07",
                    "planManagementText": "Plan-managed",
                    "supportTypeLevelDetails": [
                        {
                            "startDate": "2025-05-08",
                            "endDate": "2026-05-07",
                            "releasedAmount": 2500,
                            "remainingAmount": 2500,
                            "approvedAmount": 10000,
                            "spentAmount": 0,
                            "supportTypeText": "Core",
                            "supportCategoryLevelDetails": [
                                {
                                    "spentAmount": 0,
                                    "remainingAmount": 2500,
                                    "nextInstalmentStartDate": "2025-08-08",
                                    "nextInstalmentEndDate": "2025-11-07",
                                    "nextInstalmentReleaseAmount": 2500,
                                    "instalmentType": "Regular",
                                    "instalmentStart": "2025-05-08",
                                    "instalmentEnd": "2025-08-07",
                                    "startDate": "2025-05-08",
                                    "endDate": "2026-05-07",
                                    "createdDate": null,
                                    "releasedAmount": 2500,
                                    "approvedAmount": 10000,
                                    "supportCategoryText": "Consumables",
                                    "supportCategory": "",
                                    "description": null,
                                    "fundingComponentName": "Core Flexible (Plan-managed)",
                                    "budgetStatus": null,
                                    "fundingPeriods": [
                                        {
                                            "startDate": "2025-05-08",
                                            "endDate": "2025-08-07",
                                            "duration": "3 months",
                                            "amount": 2500,
                                            "released": "Yes"
                                        },
                                        {
                                            "startDate": "2025-08-08",
                                            "endDate": "2025-11-07",
                                            "duration": "3 months",
                                            "amount": 2500,
                                            "released": "Not yet released"
                                        },
                                        {
                                            "startDate": "2025-11-08",
                                            "endDate": "2026-02-07",
                                            "duration": "3 months",
                                            "amount": 2500,
                                            "released": "Not yet released"
                                        },
                                        {
                                            "startDate": "2026-02-08",
                                            "endDate": "2026-05-07",
                                            "duration": "3 months",
                                            "amount": 2500,
                                            "released": "Not yet released"
                                        }
                                    ]
                                }
                            ]
                        }
                    ],
                    "fundingPeriods": [
                        {
                            "startDate": "2025-05-08",
                            "endDate": "2025-08-07",
                            "duration": "3 months",
                            "amount": 2500,
                            "released": "Yes"
                        },
                        {
                            "startDate": "2025-08-08",
                            "endDate": "2025-11-07",
                            "duration": "3 months",
                            "amount": 2500,
                            "released": "Not yet released"
                        },
                        {
                            "startDate": "2025-11-08",
                            "endDate": "2026-02-07",
                            "duration": "3 months",
                            "amount": 2500,
                            "released": "Not yet released"
                        },
                        {
                            "startDate": "2026-02-08",
                            "endDate": "2026-05-07",
                            "duration": "3 months",
                            "amount": 2500,
                            "released": "Not yet released"
                        }
                    ]
                }
            ]
        },
        {
            "startDate": "2025-05-08",
            "endDate": "2026-05-07",
            "releasedAmount": 10500,
            "spentAmount": 0,
            "remainingAmount": 10500,
            "budgetTypeText": "Stated",
            "approvedAmount": 18000,
            "planManagement": [
                {
                    "startDate": "2025-05-08",
                    "endDate": "2026-05-07",
                    "remainingAmount": 10500,
                    "spentAmount": 0,
                    "releasedAmount": 10500,
                    "approvedAmount": 18000,
                    "nextInstalmentStartDate": null,
                    "nextInstalmentEndDate": null,
                    "nextInstalmentReleaseAmount": 0,
                    "instalmentStart": null,
                    "instalmentEnd": null,
                    "planManagementText": "Plan-managed",
                    "supportTypeLevelDetails": [
                        {
                            "startDate": "2025-05-08",
                            "endDate": "2026-05-07",
                            "releasedAmount": 2500,
                            "remainingAmount": 2500,
                            "approvedAmount": 10000,
                            "spentAmount": 0,
                            "supportTypeText": "Capital",
                            "supportCategoryLevelDetails": [
                                {
                                    "spentAmount": 0,
                                    "remainingAmount": 2500,
                                    "nextInstalmentStartDate": "2025-08-08",
                                    "nextInstalmentEndDate": "2025-11-07",
                                    "nextInstalmentReleaseAmount": 2500,
                                    "instalmentType": "Once-off",
                                    "instalmentStart": "2025-05-08",
                                    "instalmentEnd": "2025-08-07",
                                    "startDate": "2025-05-08",
                                    "endDate": "2026-05-07",
                                    "createdDate": null,
                                    "releasedAmount": 2500,
                                    "approvedAmount": 10000,
                                    "supportCategoryText": "Home Modifications",
                                    "supportCategory": "",
                                    "description": null,
                                    "fundingComponentName": "Home Modifications",
                                    "budgetStatus": null,
                                    "fundingPeriods": [
                                        {
                                            "startDate": "2025-05-08",
                                            "endDate": "2025-08-07",
                                            "duration": "3 months",
                                            "amount": 2500,
                                            "released": "Yes"
                                        },
                                        {
                                            "startDate": "2025-08-08",
                                            "endDate": "2025-11-07",
                                            "duration": "3 months",
                                            "amount": 2500,
                                            "released": "Not yet released"
                                        },
                                        {
                                            "startDate": "2025-11-08",
                                            "endDate": "2026-02-07",
                                            "duration": "3 months",
                                            "amount": 2500,
                                            "released": "Not yet released"
                                        },
                                        {
                                            "startDate": "2026-02-08",
                                            "endDate": "2026-05-07",
                                            "duration": "3 months",
                                            "amount": 2500,
                                            "released": "Not yet released"
                                        }
                                    ]
                                }
                            ]
                        },
                        {
                            "startDate": "2025-05-08",
                            "endDate": "2026-05-07",
                            "releasedAmount": 8000,
                            "remainingAmount": 8000,
                            "approvedAmount": 8000,
                            "spentAmount": 0,
                            "supportTypeText": "Capacity Building",
                            "supportCategoryLevelDetails": [
                                {
                                    "spentAmount": 0,
                                    "remainingAmount": 8000,
                                    "nextInstalmentStartDate": null,
                                    "nextInstalmentEndDate": null,
                                    "nextInstalmentReleaseAmount": 0,
                                    "instalmentType": "Once-off",
                                    "instalmentStart": "2025-05-08",
                                    "instalmentEnd": "2026-05-07",
                                    "startDate": "2025-05-08",
                                    "endDate": "2026-05-07",
                                    "createdDate": null,
                                    "releasedAmount": 8000,
                                    "approvedAmount": 8000,
                                    "supportCategoryText": "Choice and Control",
                                    "supportCategory": "",
                                    "description": null,
                                    "fundingComponentName": "Choice and Control",
                                    "budgetStatus": null,
                                    "fundingPeriods": [
                                        {
                                            "startDate": "2025-05-08",
                                            "endDate": "2026-05-07",
                                            "duration": "12 months",
                                            "amount": 8000,
                                            "released": "Yes"
                                        }
                                    ]
                                }
                            ]
                        }
                    ],
                    "fundingPeriods": null
                },
                {
                    "startDate": null,
                    "endDate": null,
                    "remainingAmount": 0,
                    "spentAmount": 0,
                    "releasedAmount": 0,
                    "approvedAmount": 0,
                    "nextInstalmentStartDate": null,
                    "nextInstalmentEndDate": null,
                    "nextInstalmentReleaseAmount": 0,
                    "instalmentStart": null,
                    "instalmentEnd": null,
                    "planManagementText": "Self-managed",
                    "supportTypeLevelDetails": [
                        {
                            "startDate": null,
                            "endDate": null,
                            "releasedAmount": 0,
                            "remainingAmount": 0,
                            "approvedAmount": 0,
                            "spentAmount": 0,
                            "supportTypeText": "Capacity Building",
                            "supportCategoryLevelDetails": [
                                {
                                    "spentAmount": 0,
                                    "remainingAmount": 0,
                                    "nextInstalmentStartDate": null,
                                    "nextInstalmentEndDate": null,
                                    "nextInstalmentReleaseAmount": 0,
                                    "instalmentType": null,
                                    "instalmentStart": null,
                                    "instalmentEnd": null,
                                    "startDate": null,
                                    "endDate": null,
                                    "createdDate": null,
                                    "releasedAmount": 0,
                                    "approvedAmount": 0,
                                    "supportCategoryText": "Lifelong Learning",
                                    "supportCategory": null,
                                    "description": null,
                                    "fundingComponentName": "Lifelong Learning",
                                    "budgetStatus": "Budget available",
                                    "fundingPeriods": null
                                }
                            ]
                        }
                    ],
                    "fundingPeriods": null
                },
                {
                    "startDate": null,
                    "endDate": null,
                    "remainingAmount": 0,
                    "spentAmount": 0,
                    "releasedAmount": 0,
                    "approvedAmount": 0,
                    "nextInstalmentStartDate": null,
                    "nextInstalmentEndDate": null,
                    "nextInstalmentReleaseAmount": 0,
                    "instalmentStart": null,
                    "instalmentEnd": null,
                    "planManagementText": "Agency-managed",
                    "supportTypeLevelDetails": [
                        {
                            "startDate": null,
                            "endDate": null,
                            "releasedAmount": 0,
                            "remainingAmount": 0,
                            "approvedAmount": 0,
                            "spentAmount": 0,
                            "supportTypeText": "Capital",
                            "supportCategoryLevelDetails": [
                                {
                                    "spentAmount": 0,
                                    "remainingAmount": 0,
                                    "nextInstalmentStartDate": null,
                                    "nextInstalmentEndDate": null,
                                    "nextInstalmentReleaseAmount": 0,
                                    "instalmentType": null,
                                    "instalmentStart": null,
                                    "instalmentEnd": null,
                                    "startDate": null,
                                    "endDate": null,
                                    "createdDate": null,
                                    "releasedAmount": 0,
                                    "approvedAmount": 0,
                                    "supportCategoryText": "Assistive Technology",
                                    "supportCategory": null,
                                    "description": null,
                                    "fundingComponentName": "Assistive Technology",
                                    "budgetStatus": "Budget available",
                                    "fundingPeriods": null
                                }
                            ]
                        }
                    ],
                    "fundingPeriods": null
                }
            ]
        }
    ]
}

Service Booking Management

This collection of APIs and webhooks describe the service booking management functionality available through the NDIS Extensions.

Create A Service Booking

POST /billers/{billerId}/members/{memberNumber}/serviceBookings

This resource allows the creation of service booking.

Path Parameters

FieldFormatRequired?Description
billerIdUUIDMandatoryHICAPS’s unique reference for the Biller.
memberNumberstringMandatoryMember’s identifier, as issued by the NDIS. Max 10 digits.

Service Booking Body Parameters

FieldFormatRequired?Description
memberNumberstringMandatoryMember’s identifier, as issued by the NDIS. Max 10 digits.
surnamestringMandatoryMember’s surname. Max 80 chars.
dateOfBirthstringMandatoryMember’s date of birth in YYYY-MM-DD format.
bookingTypestringMandatoryMust be ZSAG for a standard agency booking or ZPLM for Plan Managed Service bookings.
startDatestringMandatoryStart date in YYYY-MM-DD format.
endDatestringMandatoryEnd date in YYYY-MM-DD format.
planIdintegerMandatoryThe member’s plan ID. Max 10 digits.
providerCommentsstringOptionalAny provider comments to be added to the service booking.
itemsArray of Service Booking ItemsMandatoryThe list of categories and items available for this service booking.

Service Booking Items Parameters

FieldFormatRequired?Description
itemCategorystringMandatoryThe item category that is claimable.
itemCodestringOptionalThe specific item within the category that is claimable.
Note: Most service bookings will contain specific item codes but these are not mandatory if all items within a item category are claimable.
quantityintegerMandatoryThe quantity of items on the service booking.
unitPricedecimal (2dp)MandatoryThe unit price of each item.

Example Create A Service Booking Request

{
    "memberNumber": 1234567890,
    "surname": "Smith",
    "dateOfBirth": "YYYY-MM-DD",
    "bookingType": "ZSAG",
    "startDate": "YYYY-MM-DD",
    "endDate": "YYYY-MM-DD",
    "planId": 1234567890,
    "providerComments": "",
    "items": [
        {
            "itemCategory": "ASSISTIVE_TECHNOLOGY",
            "itemCode": "05_220627230_0122_1_2",
            "quantity": 2,
            "unitPrice": 123.45
        },
        {
            "itemCategory": "ASSISTIVE_TECHNOLOGY",
            "itemCode": "05_220627230_4444_1_2",
            "quantity": 1,
            "unitPrice": 45.85
        }
    ]
}

Create A Service Booking Response

HTTP 202

Service Booking Created

WEBHOOK → {onServiceBookingCreated}

This webhook will trigger once the service booking creation completes.

Path Parameters

FieldFormatRequired?Description
{onServiceBookingCreated}URIMandatoryThe URL that you provided for the onServiceBookingCreated event.

Webhook Body Parameters

FieldDescription
idA unique ID per event.
createdThe date and time of the event in Unix Epoch Time format.
dataA single Service Booking object.
typendis.member.serviceBooking.created
_linkslp:webhook-error defines the URI to POST in case the webhook needs to be replayed by HICAPS. Note: this value can be null or empty if no replay is possible.
lp:service-booking-updates-subscribe or lp:service-booking-updates-unsubscribe URIs will display depending on whether a subscription already exists or not for this service booking.

Example Service Booking Created Webhook

{
    "id": "f1fa5bb0-1fd3-4d6d-adff-fbb90871c4f8",
    "created": 1626135961,
    "data": {
        "requestId": "5ddd2328-10a1-4e3d-857e-0a5d87257a91",
        "serviceBooking": {
            "id": 123456,
            "type": "",
            "memberNumber": 123456,
            "memberName": "",
            "startDate": "YYYY-MM-DD",
            "endDate": "YYYY-MM-DD",
            "revisedEndDate": "YYYY-MM-DD",
            "inkindProgram": false,
            "status": "",
            "virtualStatus": "",
            "planId": 123456,
            "providerComments": "",
            "items": [
                {
                    "itemCategory": "ASSISTIVE_TECHNOLOGY",
                    "itemCode": "06_182488376_0111_2_2",
                    "itemDescription": "Home Modifications - Bathroom Mod - Minimal Structural Work",
                    "quantity": 3,
                    "allocatedAmount": 100,
                    "remainingAmount": 0
                }
            ]
        }
    },
    "type": "ndis.member.serviceBooking.created",
    "_links": {
        "lp:webhook-error": {
            "href": "someURL"
        },
        "lp:service-booking-updates-subscribe": {
            "href": "https://api.ndis.lanternpay.com/billers/{billerId}/members/{memberNumber}/subscribe"
        },
        "lp:service-booking-updates-unsubscribe": {
            "href": "https://api.ndis.lanternpay.com/billers/{billerId}/members/{memberNumber}/unsubscribe"
        }
    }
}

Edit A Service Booking

PATCH /billers/{billerId}/members/{memberNumber}/serviceBookings/{serviceBookingNumber}

This resource allows an existing service bookings price and quantity to be updated.

Edit a Service Booking Path Parameters

FieldFormatRequired?Description
billerIdUUIDMandatoryHICAPS’s unique reference for the Biller.
memberNumberstringMandatoryMember’s identifier, as issued by the NDIS. Max 10 digits.
serviceBookingNumberintegerMandatoryService booking reference, as issued by the NDIS. Max 10 digits.

Edit a Service Booking Body Parameters

FieldFormatRequired?Description
itemCategorystringMandatoryThis must be a valid NDIS category.
itemCodestringMandatoryThis must be a valid NDIS item code.
bookingTypestringOptionalZSAG or ZPLM, must match the booking type.
quantitynumberOptionalThe quantity of unitPrice you wish to set the service booking to (must adhere to price guide limits).
unitPricenumberMandatoryThe price of the item.

Edit A Service Booking Request

{
    "itemCategory": "CB_CHOICE_CONTROL",
    "itemCode": "14_033_0127_8_3",
    "bookingType": "ZSAG",
    "quantity": 10,
    "unitPrice": 220
}

Edit A Service Booking Response

HTTP 202

Extend A Service Booking

PATCH /billers/{billerId}/members/{memberNumber}/serviceBookings/{serviceBookingNumber}/extenddate

This endpoint allows a customer to extend an existing service booking.

Extend a Service Booking Path Parameters

FieldFormatRequired?Description
billerIdUUIDMandatoryHICAPS’s unique reference for the Biller.
memberNumberstringMandatoryMember’s identifier, as issued by the NDIS. Max 10 digits.
serviceBookingNumberintegerMandatoryService booking reference, as issued by the NDIS. Max 10 digits.

Extend a Service Booking Body Parameters

FieldFormatRequired?Description
bookingTypestringMandatoryZSAG or ZPLM, must match the booking type.
endDatestringMandatoryThe desired end date expressed in YYYY-MM-DD format.

Extend A Service Booking Request

{
    "bookingType": "ZSAG",
    "endDate": "2021-11-01"
}

Extend A Service Booking Response

HTTP 202

Service Booking Edited

WEBHOOK → {onServiceBookingEdited}

This webhook will trigger when the editing of the nominated service booking has completed. The full service booking detail will display in the webhook.

Path Parameters

FieldFormatRequired?Description
{onServiceBookingEdited}URIMandatoryThe URL that you provided for the onServiceBookingEdited event.

Webhook Body Parameters

FieldDescription
idA unique ID per event.
createdThe date and time of the event in Unix Epoch Time format.
dataserviceBookings array containing Service Booking objects.
typendis.member.serviceBooking.edited
_linkslp:webhook-error defines the URI to POST to in case the webhook needs to be replayed by HICAPS. Note: this value can be null or empty if no replay is possible.
lp:service-booking-updates-subscribe defines the templated URI to POST to in order to subscribe to all service booking changes for a member.
lp:service-booking-updates-unsubscribe defines the templated URI to POST to in order to unsubscribe from all service booking changes for a member.

Example Service Booking Edited Webhook

{
    "id": "f1fa5bb0-1fd3-4d6d-adff-fbb90871c4f8",
    "created": 1626135961,
    "data": {
        "requestId": "06d3e09b-e51a-4973-bd1e-aa2c624145ee",
        "serviceBooking": {
            "id": 123456,
            "type": "",
            "memberNumber": 123456,
            "memberName": "",
            "startDate": "YYYY-MM-DD",
            "endDate": "YYYY-MM-DD",
            "revisedEndDate": "YYYY-MM-DD",
            "inkindProgram": false,
            "status": "",
            "virtualStatus": "",
            "planId": 123456,
            "providerComments": "",
            "items": [
                {
                    "itemCategory": "ASSISTIVE_TECHNOLOGY",
                    "itemCode": "06_182488376_0111_2_2",
                    "itemDescription": "Home Modifications - Bathroom Mod - Minimal Structural Work",
                    "quantity": 3,
                    "allocatedAmount": 100,
                    "remainingAmount": 0
                }
            ]
        }
    },
    "type": "ndis.member.serviceBooking.edited",
    "_links": {
        "lp:webhook-error": {
            "href": "someURL"
        },
        "lp:service-booking-updates-subscribe": {
            "href": "https://api.ndis.lanternpay.com/billers/{billerId}/members/{memberNumber}/subscribe"
        },
        "lp:service-booking-updates-unsubscribe": {
            "href": "https://api.ndis.lanternpay.com/billers/{billerId}/members/{memberNumber}/unsubscribe"
        }
    }
}

Delete A Service Booking

DEL /billers/{billerId}/members/{memberNumber}/serviceBookings/{serviceBookingNumber}

This resource allows the provider to delete an existing service booking. No Body parameters are required for this request.

Path Parameters

FieldFormatRequired?Description
billerIdUUIDMandatoryHICAPS’s unique reference for the Biller.
memberNumberstringMandatoryMember’s identifier, as issued by the NDIS. Max 10 digits.
serviceBookingNumberintegerMandatoryService booking reference, as issued by the NDIS. Max 10 digits.

Delete A Service Booking Response

HTTP 202

Service Booking Deleted

WEBHOOK → {onServiceBookingDeleted}

This webhook will trigger when the deletion of a service booking has completed.

Path Parameters

FieldFormatRequired?Description
{onServiceBookingDeleted}URIMandatoryThe URL that you provided for the onServiceBookingDeleted event.

Webhook Body Parameters

FieldDescription
idA unique ID per event.
createdThe date and time of the event in Unix Epoch Time format.
dataConfirms the service booking number of the service booking that was deleted.
typendis.member.serviceBooking.deleted
_linkslp:webhook-error defines the URI to POST to in case the webhook needs to be replayed by HICAPS. Note: this value can be null or empty if no replay is possible.
lp:service-booking-updates-subscribe defines the templated URI to POST to in order to subscribe to all service booking changes for a member.
lp:service-booking-updates-unsubscribe defines the templated URI to POST to in order to unsubscribe from all service booking changes for a member.

Example Service Booking Deleted Webhook

{
    "id": "f1fa5bb0-1fd3-4d6d-adff-fbb90871c4f8",
    "created": 1626135961,
    "data": {
        "requestId": "d889136c-a0d5-4b83-853f-b01a5acf2832",
        "serviceBookingNumber": "1234567890"
    },
    "type": "ndis.member.serviceBooking.deleted",
    "_links": {
        "lp:webhook-error": {
            "href": "someURL"
        },
        "lp:service-booking-updates-unsubscribe": {
            "href": "https://api.ndis.lanternpay.com/billers/{billerId}/members/{memberNumber}/unsubscribe"
        }
    }
}

Request A Service Booking

POST /billers/{billerId}/members/{memberNumber}/serviceBookings/{serviceBookingNumber}/retrieve

This resource allows retrieval of a specific service booking.

Path Parameters

FieldFormatRequired?Description
billerIdUUIDMandatoryHICAPS’s unique reference for the Biller.
memberNumberstringMandatoryMember’s identifier, as issued by the NDIS. Max 10 digits.
serviceBookingNumberintegerMandatoryService booking reference, as issued by the NDIS. Max 10 digits.

Body Parameters

No body parameters are required for this request.

Request A Service Booking Response

HTTP 202

Service Booking Retrieved

WEBHOOK → {onServiceBookingRetrieved}

This webhook will trigger when a specific service booking has been retrieved.

Path Parameters

FieldFormatRequired?Description
{onServiceBookingRetrieved}URIMandatoryThe URL that you provided for the onServiceBookingRetrieved event.

Webhook Body Parameters

FieldDescription
idA unique ID per event.
createdThe date and time of the event in Unix Epoch Time format.
dataA single Service Booking object.
typendis.member.serviceBooking.retrieved
_linkslp:webhook-error defines the URI to POST in case the webhook needs to be replayed by HICAPS. Note: this value can be null or empty if no replay is possible.
lp:service-booking-updates-subscribe or lp:service-booking-updates-unsubscribe URIs will display depending on whether a subscription already exists or not for this service booking.

Service Booking Parameters

FieldFormatRequired?Description
idintegerMandatoryThe service booking reference, as issued by the NDIS. Max 10 digits.
typestringMandatoryThe service booking type
memberNumberstringMandatoryThe member number, as issued by the NDIS. Max 10 digits.
memberNamestringMandatoryThe member’s full name.
startDatedate
YYYY-MM-DD
MandatoryThe start date of the service booking.
endDatedate
YYYY-MM-DD
MandatoryThe end date of the service booking.
revisedEndDatedate
YYYY-MM-DD
MandatoryThe new service booking end date, if changed.
inkindProgrambooleanMandatory
statusstringMandatoryThe current status of the service booking.
Values include: Approved, Rejected, Deleted, Awaiting Provider Approval, etc.
virtualStatusstringMandatoryIndicates whether the service booking is Active or Inactive.
planIdintegerMandatoryThe member’s plan reference, as issued by the NDIS. Max 10 digits.
providerCommentsstringMandatoryAny comments associated with the service booking.
itemsArray of Service Booking ItemsMandatoryAll items associated with the service booking.

Service Booking Items

FieldFormatRequired?Description
itemCategorystringMandatoryThe item’s category.
itemCodestringMandatoryThe item’s code.
itemDescriptionstringMandatoryThe item’s description.
quantityintegerMandatoryThe quantity of this item on the service booking.
allocatedAmountdecimal (2dp)MandatoryThe total amount of funds allocated to this item for this service booking.
remainingAmountdecimal (2dp)MandatoryThe remaining balance of funds allocated to this item for this service booking.

Example Service Booking Retrieved Webhook

{
    "id": "f1fa5bb0-1fd3-4d6d-adff-fbb90871c4f8",
    "created": 1626135961,
    "data": {
        "requestId": "2d25644b-946d-4abd-947b-7cda0cd0b129",
        "serviceBooking": {
            "id": 123456,
            "type": "",
            "memberNumber": 123456,
            "memberName": "",
            "startDate": "YYYY-MM-DD",
            "endDate": "YYYY-MM-DD",
            "revisedEndDate": "YYYY-MM-DD",
            "inkindProgram": false,
            "status": "",
            "virtualStatus": "",
            "planId": 123456,
            "providerComments": "",
            "items": [
                {
                    "itemCategory": "ASSISTIVE_TECHNOLOGY",
                    "itemCode": "06_182488376_0111_2_2",
                    "itemDescription": "Home Modifications - Bathroom Mod - Minimal Structural Work",
                    "quantity": 3,
                    "allocatedAmount": 100,
                    "remainingAmount": 0
                }
            ]
        }
    },
    "type": "ndis.member.serviceBooking.retrieved",
    "_links": {
        "lp:webhook-error": {
            "href": "someURL"
        },
        "lp:service-booking-updates-subscribe": {
            "href": "https://api.ndis.lanternpay.com/billers/{billerId}/members/{memberNumber}/subscribe"
        },
        "lp:service-booking-updates-unsubscribe": {
            "href": "https://api.ndis.lanternpay.com/billers/{billerId}/members/{memberNumber}/unsubscribe"
        }
    }
}

Request Service Bookings

POST /billers/{billerId}/members/{memberNumber}/serviceBookings/retrieve

This resource allows retrieval of a list of all the biller’s service bookings for a specific member. Once the data is retrieved the Service Bookings Retrieved webhook will fire containing all the service booking detail for that member.

Path Parameters

FieldFormatRequired?Description
billerIdUUIDMandatoryHICAPS’s unique reference for the Biller.
memberNumberstringMandatoryMember’s identifier, as issued by the NDIS. Max 10 digits.

Body Parameters

No body parameters are required for this request.

Request Service Bookings Response

HTTP 202

Service Bookings Retrieved

WEBHOOK → {onServiceBookingsRetrieved}

This webhook will trigger when all of the biller’s service bookings for a specific member have been retrieved.

Path Parameters

FieldFormatRequired?Description
{onServiceBookingsRetrieved}URIMandatoryThe URL that you provided for the onServiceBookingsRetrieved event.

Webhook Body Parameters

FieldDescription
idA unique ID per event.
createdThe date and time of the event in Unix Epoch Time format.
dataserviceBookings array containing Service Booking objects.
typendis.member.serviceBookings.retrieved
_linkslp:webhook-error defines the URI to POST to in case the webhook needs to be replayed by HICAPS. Note: this value can be null or empty if no replay is possible.
lp:service-booking-updates-subscribe defines the templated URI to POST to in order to subscribe to all service booking changes for a member.
lp:service-booking-updates-unsubscribe defines the templated URI to POST to in order to unsubscribe from all service booking changes for a member.

Example Service Bookings Retrieved Webhook

{
    "id": "f1fa5bb0-1fd3-4d6d-adff-fbb90871c4f8",
    "created": 1626135961,
    "data": {
        "requestId": "3348a6e7-b72e-4b43-bcc4-87d8d2899f0d",
        "serviceBookings": [
            {
                "id": 123456,
                "type": "",
                "memberNumber": 123456789,
                "memberName": "",
                "startDate": "YYYY-MM-DD",
                "endDate": "YYYY-MM-DD",
                "revisedEndDate": "YYYY-MM-DD",
                "inkindProgram": false,
                "status": "",
                "virtualStatus": "",
                "planId": 12345678,
                "providerComments": "",
                "items": [
                    {
                        "itemCategory": "ASSISTIVE_TECHNOLOGY",
                        "itemCode": "06_182488376_0111_2_2",
                        "itemDescription": "Home Modifications - Bathroom Mod - Minimal Structural Work",
                        "quantity": 3,
                        "allocatedAmount": 100,
                        "remainingAmount": 0
                    }
                ]
            },
            {
                "id": 654321,
                "type": "",
                "memberNumber": 987654321,
                "memberName": "",
                "startDate": "YYYY-MM-DD",
                "endDate": "YYYY-MM-DD",
                "revisedEndDate": "YYYY-MM-DD",
                "inkindProgram": false,
                "status": "",
                "virtualStatus": "",
                "planId": 7654321,
                "providerComments": "",
                "items": [
                    {
                        "itemCategory": "ASSISTIVE_TECHNOLOGY",
                        "itemCode": "06_182488376_0111_2_2",
                        "itemDescription": "Home Modifications - Bathroom Mod - Minimal Structural Work",
                        "quantity": 3,
                        "allocatedAmount": 100,
                        "remainingAmount": 0
                    }
                ]
            }
        ]
    },
    "type": "ndis.member.serviceBookings.retrieved",
    "_links": {
        "lp:webhook-error": {
            "href": "someURL"
        },
        "lp:service-booking-updates-subscribe": {
            "href": "https://api.ndis.lanternpay.com/billers/{billerId}/members/{memberNumber}/subscribe"
        },
        "lp:service-booking-updates-unsubscribe": {
            "href": "https://api.ndis.lanternpay.com/billers/{billerId}/members/{memberNumber}/unsubscribe"
        }
    }
}

Service Booking Updated

WEBHOOK → {onServiceBookingUpdated}

This webhook will trigger whenever a service booking has been updated and will contain the entire service booking details.

Path Parameters

FieldFormatRequired?Description
{onServiceBookingUpdated}URIMandatoryThe URL that you provided for the onServiceBookingUpdated event.

Webhook Body Parameters

FieldDescription
idA unique ID per event.
createdThe date and time of the event in Unix Epoch Time format.
dataserviceBooking object containing Service Booking Detail View data.
typendis.member.serviceBooking.updated
_linkslp:webhook-error defines the URI to POST in case the webhook needs to be replayed by HICAPS. Note: this value can be null or empty if no replay is possible.
lp:service-booking-updates-unsubscribe defines the URI to post to in order to delete the subscription for this service booking.

Example Service Booking Updated Webhook

{
    "id": "f1fa5bb0-1fd3-4d6d-adff-fbb90871c4f8",
    "created": 1626135961,
    "data": {
        "serviceBooking": {
            "id": 123456,
            "type": "",
            "memberNumber": 123456,
            "memberName": "",
            "startDate": "YYYY-MM-DD",
            "endDate": "YYYY-MM-DD",
            "revisedEndDate": "YYYY-MM-DD",
            "inkindProgram": false,
            "status": "",
            "virtualStatus": "",
            "memberPlanId": 123456,
            "providerComments": "",
            "items": [
                {
                    "itemCategory": "ASSISTIVE_TECHNOLOGY",
                    "itemCode": "06_182488376_0111_2_2",
                    "itemDescription": "Home Modifications - Bathroom Mod - Minimal Structural Work",
                    "quantity": 3,
                    "allocatedAmount": 100,
                    "remainingAmount": 0
                }
            ]
        }
    },
    "type": "ndis.member.serviceBooking.updated",
    "_links": {
        "lp:webhook-error": {
            "href": "someURL"
        },
        "lp:service-booking-updates-subscribe": {
            "href": "https://api.ndis.lanternpay.com/billers/{billerId}/members/{memberNumber}/serviceBookings/{serviceBookingNumber}/subscribe"
        }
    }
}

Notification Subscription Management

This section describes the API actions available to manage all NDIS API related notification subscriptions, including view, subscribe and unsubscribe actions.

Subscribe to a Member

POST /billers/{billerId}/members/{memberNumber}/subscribe

This resource subscribes to a member so that whenever any of that member’s service bookings are updated (i.e. when the onServiceBookingUpdated event occurs) a notification webhook is triggered containing the service bookings for the subscribed participant. This endpoint accepts an optional tenantId field, which enables you to provide an identifier for participants who may exist across multiple tenants/subscriptions.

Path Parameters

FieldFormatRequired?Description
billerIdUUIDMandatoryHICAPS’s unique reference for the Biller.
memberNumberstringMandatoryMember’s identifier, as issued by the NDIS. Max 10 digits.

Body Parameters

FieldFormatRequired?Description
tenantIdstringOptionalThis field can optionally be included. When included each subsription is considered unique in the context of the tenantId provided. This allows for multiple tenants to have subscriptions for the same participant using separate correlation identifiers. For example a subscription can exist for member 123456, using tenantId A and B, at the same time; this means any updates that are trigger will result in an update webhook for tenant A and tenant B with corresponding correlation identifiers.

Subscribe to a Member Response

HTTP 202

Member Subscribed

WEBHOOK → {onMemberSubscribed}

This webhook will trigger once the creation of subscriptions to all of a member’s service bookings is complete.

Path Parameters

FieldFormatRequired?Description
{onMemberSubscribed}URIMandatoryThe URL that you provided for the onMemberSubscribed event.

Webhook Body Parameters

FieldDescription
idA unique ID per event.
createdThe date and time of the event in Unix Epoch Time format.
dataConfirms the member number for the member whose service bookings have been subscribed to.
typendis.member.serviceBookingUpdates.subscribed
_linkslp:webhook-error defines the URI to POST in case the webhook needs to be replayed by HICAPS. Note: this value can be null or empty if no replay is possible.
lp:service-booking-updates-unsubscribe defines a templated URI to post to in order to unsubscribe from this member.

Example Member Subscribed Webhook

{
    "id": "f1fa5bb0-1fd3-4d6d-adff-fbb90871c4f8",
    "created": 1626135961,
    "data": {
        "memberNumber": 123456
    },
    "type": "ndis.member.serviceBookingUpdates.subscribed",
    "_links": {
        "lp:webhook-error": {
            "href": "someURL"
        },
        "lp:service-booking-updates-unsubscribe": {
            "href": "https://api.ndis.lanternpay.com/billers/{billerId}/members/{memberNumber}/unsubscribe"
        }
    }
}

Unsubscribe from a Member

POST /billers/{billerId}/members/{memberNumber}/unsubscribe

This resource unsubscribes from a member so no webhooks are triggered when any of their service bookings are updated.

Path Parameters

FieldFormatRequired?Description
billerIdUUIDMandatoryHICAPS’s unique reference for the Biller.
memberNumberstringMandatoryMember’s identifier, as issued by the NDIS. Max 10 digits.

Body Parameters

No body parameters are required for this request.

Unsubscribe from a Member Response

HTTP 202

Member Unsubscribed

WEBHOOK → {onMemberUnsubscribed}

This webhook will trigger once the removal of all of a member’s service booking subscriptions is complete.

Path Parameters

FieldFormatRequired?Description
{onMemberUnsubscribed}URIMandatoryThe URL that you provided for the onMemberUnsubscribed event.

Webhook Body Parameters

FieldDescription
idA unique ID per event.
createdThe date and time of the event in Unix Epoch Time format.
dataConfirms the member number for the member whose service bookings subscriptions have been removed.
typendis.member.serviceBookingUpdates.unsubscribed
_linkslp:webhook-error defines the URI to POST in case the webhook needs to be replayed by HICAPS. Note: this value can be null or empty if no replay is possible.
lp:service-booking-updates-subscribe defines a templated URI to post to in order to subscribe to this member.

Example Member Unsubscribed Webhook

{
    "id": "f1fa5bb0-1fd3-4d6d-adff-fbb90871c4f8",
    "created": 1626135961,
    "data": {
        "memberNumber": 123456
    },
    "type": "ndis.member.serviceBookingUpdates.unsubscribed",
    "_links": {
        "lp:webhook-error": {
            "href": "someURL"
        },
        "lp:service-booking-updates-subscribe": {
            "href": "https://api.ndis.lanternpay.com/billers/{billerId}/members/{memberNumber}/subscribe"
        }
    }
}

Request Subscribed Members

POST /billers/{billerId}/memberSubscriptions

This resource allows retrieval of a list of all members with active service booking subscriptions.

Path Parameters

FieldFormatRequired?Description
billerIdUUIDMandatoryHICAPS’s unique reference for the Biller.
memberNumberstringMandatoryMember’s identifier, as issued by the NDIS. Max 10 digits.

Body Parameters

No body parameters are required for this request.

Request Subscribed Members Response

HTTP 202

Subscribed Members Retrieved

WEBHOOK → {onSubscribedMembersRetrieved}

This webhook will trigger once the list of members with active subscriptions has been retrieved.

Path Parameters

FieldFormatRequired?Description
{onSubscribedMembersRetrieved}URIMandatoryThe URL that you provided for the onSubscribedMembersRetrieved event.

Webhook Body Parameters

FieldDescription
idA unique ID per event.
createdThe date and time of the event in Unix Epoch Time format.
datasubscribedMembers array containing each member number with an active subscription to service booking updates.
typendis.member.activeSubscriptions.retrieved
_linkslp:webhook-error defines the URI to POST in case the webhook needs to be replayed by HICAPS. Note: this value can be null or empty if no replay is possible.
lp:service-booking-updates-unsubscribe defines a templated URI to post to in order to unsubscribe from a member.

Example Active Subscriptions Retrieved Webhook

{
    "id": "f1fa5bb0-1fd3-4d6d-adff-fbb90871c4f8",
    "created": 1626135961,
    "data": {
        "subscribedMembers": [
            {
                "memberNumber": 123456
            },
            {
                "memberNumber": 654321
            }
        ]
    },
    "type": "ndis.member.activeSubscriptions.retrieved",
    "_links": {
        "lp:webhook-error": {
            "href": "someURL"
        },
        "lp:service-booking-updates-unsubscribe": {
            "href": "https://api.ndis.lanternpay.com/billers/{billerId}/members/{memberNumber}/unsubscribe"
        }
    }
}

Medicare API Extensions

Base URIs

For Medicare API extensions, all URIs in this section are relative to the standard Base URIs.

Assignment of Benefits

Assignment of Benefits (AoB) is the patient’s consent for their Medicare benefit to be paid directly to the biller, rather than to the patient. Where an assignment of benefit applies, the biller must present the assignment of benefit form to the patient, capture their agreement, and provide the patient with a copy of the completed form.

The Assignment of Benefits extension allows you to retrieve the forms that HICAPS has generated for an invoice so they can be presented to the patient and retained against your records. It applies to all Medicare sub-types.

Get Invoice Forms

GET /invoices/{invoiceId}/forms

This resource allows you to retrieve the forms associated with a Medicare invoice, including the Assignment of Benefit form. The invoice must have been successfully submitted before its forms can be retrieved.

Path Parameters

FieldFormatRequired?Description
invoiceIdUUIDMandatoryHICAPS’s unique reference for the invoice to retrieve the forms for.

Get Invoice Forms Response Parameters

Example Get Invoice Forms Response

Note: this response is synchronous