Provider API

Alert This is the current specification (v2.0) for our Provider API, released in January 2020. If you are looking for the deprecated v1.0 specification, click here.

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 are based on three principles:

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

Definitions

Programs

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

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

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

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. Ususally these are the same person but sometimes they may be different.

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

A member is defined at the invoice level, as defined in the Member 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)

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 requried action(s).

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

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

Note: Actions are defined at the invoice level, not the claim level, because an action pending on any one claim 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.

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

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

State Enum Value Definition User’s expected reaction to the state
AWAITING CANCEL RESPONSE awaitingCancelResponse The biller has asked to cancel this claim, awaiting confirmation from Program that it is cancelled. Biller may wait for a short while to see if the cancellation is approved. They expect an update when the cancellation is confirmed.
CANCEL PENDING cancelPending The program has received the cancellation request but is not able to process it automatically. Program will send another update soon. Biller is aware that the cancellation request has been received and is being processed.
CANCELLED cancelled Program has processed the cancelation request and cancelled the claim in their system. Depends on the context:
  1. If payment has not been made yet, Biller expects 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.

State Enum Value Definition User’s expected reaction to the state
SENT sent The payment has been sent to the bank for processing Biller expects that the payment with the specified claims will have been included in a recent payment to their bank account (within banking timeframes)
FAILED failed The payment has failed Biller expects to be contacted about how to rectify the issues with the bank account details
HELD held The payment has been held Biller expects to be contacted about how to rectify the issues with the bank account details
OVERPAID overpaid The payment has been made in excess of the approved claim Biller 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 retreive 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:

Environment URI Description
Sandbox https://auth.sandbox.lanternpay.com This is a pre-production environment you can use for testing.
Production https://auth.lanternpay.com This is the production environment.
How to retrieve initial security tokens after user authorization

POST /oauth2/token

Message Part Type Details
Header BasicAuth Your application’s client_id and client_secret, base64 encoded.
Body x-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 Part Type Details
Header BasicAuth Your application’s client_id and client_secret, base64 encoded.
Body x-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:

Environment URI Description
Sandbox https://api.auth.sandbox.lanternpay.com This is a pre-production environment you can use for testing.
Production https://api.auth.lanternpay.com This 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 Part Type Details
Header BasicAuth N/A - no header auth is used
Body x-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:

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

API Error Payload

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

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

Invalid Parameters

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

Example API Error Payload

{
    "type": "https://example.net/validation-error",
    "title": "Your request parameters didn't validate.",
    "invalidParams": [
        {
            "name": "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.

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

Webhook Standard Payload

Each webhook will have the following standard payload:

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

Webhook Authentication

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

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

Asynchronous Webhook Handlers

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

Retry Policy

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

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

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

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

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 Aysnchrnous Webhook Handlers, it is expected that whenever possible notifications are processed by your application a-synchronously. 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 a-synchronously.

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:

Environment URI Description
Sandbox https://api.notificationcache.sandbox.lanternpay.com The is a pre-production environment used for testing.
Production https://api.notificationcache.lanternpay.com This is the production environment.
Get Notifications

GET /billers/{billerId}/notifications

Path Parameters
Field Format Required? Description
billerId UUID Mandatory HICAPS’s unique reference for the Biller.
Query Parameters
Field Format Required? Description
maxNumberOfMessages integer Optional The maximum number of messages to retreve 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.

Field Format Required? Description
receiptHandle string Mandatory This 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.
notification Notification Mandatory The notification object, defined in the table below.
Notification Object Parameters
Field Format Required? Description
id UUID Mandatory This 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.
message object Mandatory The 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
Field Format Required? Description
billerId UUID Mandatory HICAPS’s unique reference for the Biller.
notificationId UUID Mandatory The unique reference for the notification retrieved from the cache.
Delete A Notification Body Parameters
Field Format Required? Description
receiptHandle string Mandatory The 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:

Environment URI Description
Sandbox https://api.providers.sandbox.lanternpay.com This is a pre-production environment used for testing.
Production https://api.providers.lanternpay.com This is the production environment.

Root

The root resource is the starting point for all API operations when using HATEAOS hypermedia to navigate the API. The first step is to obtain 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

Field Format Required? Description
billerId UUID Mandatory HICAPS’s unique reference for the Biller.

Invoice Body Parameters

Field Format Required? Description
billerInvoiceId string Conditional The 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.
program string Mandatory Short name of the target program.
See the list of Program codes here.
responsePriority string Mandatory Indicates to the Program the expected SLA for response.
Values include: stat (immediately/real time), normal (with best effort), deferred (later, when possible).
created dateTime
YYYY-MM-DDTHH:mm:ss.SSS±HH:mm		 Mandatory dateTime of creation of this entity in the PMS.
invoiceNumber string Conditional The 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.
invoiceDate date
YYYY-MM-DD		 Conditional Date of original invoice
member Member Mandatory The entity who the claim is for.
patient Patient Conditional The patient parameters at the invoice level are for medicare claims only.
For all other programs, use the patient parameters are the claim level.
invoiceCustomFields InvoiceCustomFields Conditional Other invoice-level fields associated with this invoice, as required by the program.
claims An array of Claims Mandatory List of claims (invoice line items).

Member Parameters

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

MemberCustomFields Parameters

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

Field Format Required? Description
personIdentifier string Conditional This is the individual identifier of the person making the claim (for the whole invoice), as shown on the membership card.
For example, if the person is listed as the 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 are 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.

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

PatientCustomFields Parameters

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

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

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

InvoiceCustomFields Parameters

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

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

Medicare Invoice Parameters

Field Format Required? Description
payeeProviderNumber string Conditional The provider number of the payee provider, if different from the servicing provider.
cevRequestIndicator string Conditional The 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.
isFullyPaidByClient boolean Conditional Set 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.

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

Referral Provider Parameters

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

Medicare DVA Parameters

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

Medicare DVA Disability Parameters

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

NDIS Invoice Parameters

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

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

NDIS Payee Invoice Parameters

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

WCQ Invoice Parameters

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

ICare Invoice Parameters

Field Format Required? Description
caseNumber string Mandatory The Case Number issued to the patient by ICare for this treatment.

Claims Parameters

Field Format Required? Description
billerClaimId String Conditional Invoice 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.
provider Provider Conditional Provider is the entity (person/organisation) who performed the work. Required by some Programs.
itemPublisher string conditional The entity that has responsibility for the item code. Could be defaulted by PMS in specific sectors. Example values include: fred, pbs, mims, ndis, tac.
itemCode string Mandatory The unique identifier for the service or good.
description string Conditional Description of the item or service.
itemCustomFields ItemCustomFields Conditional Additional service details, as required for some programs.
patient Patient Conditional If the patient receiving the service is different to the member (e.g. Parent/Child). Required by some programs.
serviceDate date
YYYY-MM-DD		 Conditional The date that the service was performed in date format. Required if serviceDateTime or servicePeriod is not provided.
serviceDateTime dateTime
YYYY-MM-DDTHH:mm:ss.sss±HH:mm		 Conditional The date and time that the service was performed in dateTime format. Required if serviceDate or servicePeriod is not provided.
servicePeriod Period Conditional The start and end date and time that the service was performed in dateTime format. Required if serviceDate or serviceDateTime is not provided.
location Location Conditional Location where the service occurs.
consentReceived boolean Conditional Client/patient consent has been granted.
consentAuthority string Conditional The party who has the consent record.
quantity decimal (4 dp) Conditional Note: the unit of measure is defined by the program for each item. 4 dp is required to allow quantity * price to equal a specific total.
Note that for Medicare Easyclaim transactions, the quantity for each claim line is always one.
unitPrice decimal (4 dp) Conditional The 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.
taxCode string Conditional Values 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.
contractNumber string Conditional The contract that this claim is claimed against.
contractLineItemNumber string Conditional The contract line item that this claim is claimed against.

Provider Parameters

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

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

Person Parameters

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

Organization Parameters

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

Registrations Parameters

Field Format Required? Description
ahpraRegistrationNumber string Conditional The AHPRA number of the provider.
medicareProviderNumber string Conditional The Medicare number of the provider.
medibankProviderNumber string Conditional The Medibank number of the provider.
worksafevicProviderNumber string Conditional The Worksafe Victoria number of the provider.
pbsPharmacyApprovalNumber string Conditional The PBS Pharmacy Approval number of the provider.
workCoverQldProviderNumber string Conditional The Work Cover QLD number of the provider.
hbfProviderNumber string Conditional The HBF Provider Number of the provider.

ContactPoint Parameters

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

Provider Disciplines

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

Click to expand

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

ItemCustomFields Parameters

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

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

NDIS Parameters

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

NDIS ABN Values

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

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

Medicare Claim Parameters

Field Format Required? Description
distance integer Conditional The distance in km, e.g. 15
Note: itemCode must be set to "KM" if distance is used.
Additionally, distance cannot be used if location.type=R
duplicateServiceOverride boolean Conditional Set to true if 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.
afterCareOverride boolean Conditional Set to true to indicate that a service is not normal aftercare (i.e. treated for an unrelated condition or for complications form the operation)
lspNumber string Conditional The 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.
equipmentId string Conditional The equipment ID required for certain Medicare Easyclaim invoices. Equipment ID is up to 5 characters.
selfDeemedCode string Conditional The 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
specimenCollectionPointId string Conditional Required for Medicare Easyclaim Bulkbill pathology invoices only. Length up to 4 characters.
amountPaidByClient decimal (2dp) Conditional Use 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

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

Pharmacy Parameters

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

Ambulance Parameters

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

Pathologist Parameters

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

Radiologist Parameters

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

Dental Parameters

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

Patient Parameters

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

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

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

PatientCustomFields Parameters

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

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

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

Period Parameters

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

Location Parameters

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

Address Parameters

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

Position Parameters

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

Example 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

Field Format Required? Description
invoiceId UUID Mandatory The reference of the invoice to be cancelled

Body Parameters

Field Format Required? Description
invoiceId UUID Mandatory HICAPS’s unique reference of the invoice. This is the invoiceId of the invoice to be cancelled by the user.
reason string Conditional A 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

Field Format Required? Description
{onInvoiceClaimingStatusUpdated} URI Mandatory The URI that you provided during onboarding for the claiming.invoice.updated event.

Webhook Body Parameters

Field Description
id A unique ID per event.
created The date and time of the event in Unix Epoch Time format.
data Schema follows the structure of a Claiming Status Update
type claiming.invoice.updated
_links lp: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

Field Format Required? Description
invoiceId UUID Mandatory HICAPS’s reference for the invoice.
state enum Conditional The 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.)
claimStatuses Array of ClaimStatuses Mandatory An array of responses to the claims (line items) on the invoice.
invalidParams Array of Invalid Parameters Conditional An array of fields and their associated errors, at the invoice level. Where specified, this data may be used to highlight particular fields within claims which are leading to a rejection or lesser funding result.
actions Array of Actions Conditional An optional list of actions the user can take if there are issues with the claim.

ClaimStatuses Parameters

Field Format Required? Description
claimId UUID Mandatory HICAPS’s reference to this claim.
billerClaimId String Conditional Invoice line item identifier from the user’s application, eg. PMS.
programClaimId String Conditional The Program’s identifier for the claim. For the NDIS this is the Payment Reference Number
benefit decimal Conditional The amount that will be paid by the program for this claim.
adjudications An array of Adjudications Conditional The adjudication provides additional detail on the various components of the funding decision. The Adjudication information does not have any impact on the amount paid by the program (benefit).
state enum Mandatory The state of the claim as determined by the program. Values include: provisionallyApproved, approved, rejected. These values are described in the Claim State table.
statusTitle string Conditional Displayed 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.
statusDescription string Conditional Displayed to the user as the description for the claim.
invalidParams Array of Invalid Parameters Conditional An array of fields and their associated errors, at the claim level. Where specified, this data may be used to highlight particular fields within claims which are leading to a rejection or lesser funding result.

Adjudications Parameters

Field Format Required? Description
reason string Conditional Provides a text description of the adjudication result. This is why the decision has been made. E.g. “Eligible amount”, “Bonus”, “Loyalty”, “Deductible”, “Eligible Percentage”
amount decimal Conditional Formatted to two decimal places. Used where the category refers to a monetary amount. Eg. 20.00.
value string Conditional Used 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.

Field Format Required? Description
title string Conditional A short title for the action which may display as a tooltip.
description string Conditional A contextual description of the action required to be taken by the provider.
href URI Conditional A link, if applicable, the user can follow for more infomration or to complete the action.
class string Conditional The 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

Field Format Required? Description
{onInvoicePaymentStatusUpdated} URI Mandatory The URI that you provided during onboarding for the payment.invoice.updated event.

Webhook Body Parameters

Field Description
id A unique ID per event.
created The date and time of the event in Unix Epoch Time format.
data Schema follows the structure of a Payment Status Update
type payment.invoice.updated
_links lp: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

Field Format Required? Description
invoiceId UUID Mandatory HICAPS’s reference for the invoice.
paymentId UUID Mandatory LatnernPay’s reference for the payment.
state enum Mandatory The state of the payment. Values include: sent, failed, held, overpaid
claimTransactions Array of Claim Transactions Mandatory An array transactions for each claim on the invoice.

Claim Transactions Parameters

Field Format Required? Description
claimId UUID Mandatory HICAPS’s reference to this claim.
amount decimal (2 dp) Mandatory The 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)

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

Submit Predetermination

POST /billers/{billerId}/predetermination

Path Parameters

Field Format Required? Description
billerId UUID Mandatory HICAPS’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

Field Format Required? Description
{onPredeterminationStatusUpdated} URI Mandatory The URI that you provided for the onPredeterminationStatusUpdated event.

Webhook Body Parameters

Field Description
id A unique ID per event.
created The date and time of the event in Unix Epoch Time format.
type claiming.predetermination.updated
data Schema follows the structure of a Claiming Status Update webhook (i.e. the same as the Invoice Updated webhook structure)
_links lp: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

Field Format Required? Description
member Member Object Mandatory Same 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.
program string Mandatory The 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 a-synchronous 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

Field Format Required? Description
{onMemberVerificationUpdated} URI Mandatory The URI that you provided for the onMemberVerificationUpdated event.

Webhook Body Parameters

Field Description
id A unique ID per event.
created The date and time of the event in Unix Epoch Time format.
type member.verification.updated
data memberVerificationRequestId 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
_links lp: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

Field Format Required? Description
state string Conditional The current state of the member with the Program.
Either verified or unverified
statusTitle string Conditional Optionally displayed to the user as the status of the member to provide a better label than just the state value.
statusDescription string Conditional Optionally displayed to the user as the description for the status of the member - used to provide extra information/context.
programStatusCode string Conditional The status code provided by the program, if any. Refer to program’s documentation for information about specific status codes provided.
invalidParams Array of Invalid Parameters Conditional An 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:

Environment URI Description
Sandbox https://api.items.sandbox.lanternpay.com The is a pre-production environment used for testing.
Production https://api.items.lanternpay.com This is the production environment.

POST /items/search

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

Item Search Request Body Paramaters

Field Format Required? Description
query string Mandatory Text string being searched. Must be minimum of 3 characters.
filters Item Filters Mandatory An object of filters to apply to the search.
pageSize integer Optional The number of items returned per results page. Default is 50, maximum is 100.
offset integer Optional The 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

Field Format Required? Description
program string Mandatory The program’s items that are being searched. Valid program codes can be seen here.
discipline string Mandatory The provider’s discipline. Valid disciplines can be seen here.
code string Optional The 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

Field Format Required? Description
items Items Mandatory The array of items in the search results.
pageInfo Page Info Mandatory The page info for the currently returned search page.

Items Parameters

Field Format Required? Description
code string Mandatory The item code that the program knows the item by.
name string Mandatory The name of the item.
description string Mandatory The description of the item, if included.
price decimal (2dp) Mandatory The default item price, if included.
publisher string Mandatory The item publisher that the program knows the item by.

Page Info Parameters

Field Format Required? Description
pageSize integer Mandatory The page size as per the search request
offset integer Mandatory The 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.
total integer Mandatory The 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:

Environment URI Description
Sandbox https://api.terminals.sandbox.lanternpay.com The is a pre-production environment used for testing.
Production https://api.terminals.lanternpay.com This 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

Field Format Required? Description
billerId UUID Mandatory HICAPS’s unique reference for the Biller.

Get Biller Details Response Parameters

Field Format Required? Description
merchantId string Mandatory The unique merchant ID for this merchant, as stored on the temrinal. Can be null if no merchant details exist for this biller.
merchantName string Mandatory The 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 resouce 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

Field Format Required? Description
billerId UUID Mandatory HICAPS’s unique reference for the Biller.

Query Parameters

Field Format Required? Description
lastSeenInMinutes integer Optional Allows 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

Field Format Required? Description
terminals Array of Terminals Mandatory Array of terminal objects found for this biller.

Terminals Parameters

Field Format Required? Description
terminalId string Mandatory The terminal’s ID, as stored on the terminal.
lastSeenAt dateTime
YYYY-MM-DDTHH:mm:ss.SSS±HH:mm		 Mandatory The 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 resouce allows you to retrieve additional details, including provider details, of a specific terminal.

Path Parameters

Field Format Required? Description
billerId UUID Mandatory HICAPS’s unique reference for the Biller.
terminalId string Mandatory The terminal’s ID, as stored on the terminal.

Get Terminal Details Response Parameters

Field Format Required? Description
terminalId string Mandatory The terminal’s ID, as stored on the terminal.
lastSeenAt dateTime
YYYY-MM-DDTHH:mm:ss.SSS±HH:mm		 Mandatory The date/time (and time zone) of when this terminal was last active.
providers Array of Providers Optional Array of provider objects found for this merchant on this terminal. Can be null if no providers on this terminal.

Providers Parameters

Field Format Required? Description
providerNumber string Mandatory The provider number for this provider, as stored on the temrinal.
providerName string Mandatory The provider name for this provider, as stored on the temrinal.

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

Field Format Required? Description
billerId UUID Mandatory HICAPS’s unique reference for the Biller.
terminalId string Mandatory The 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

Field Format Required? Description
{onTerminalTestCompleted} URI Mandatory The URI that you provided during onboarding for the terminal.test.completed event.

Webhook Body Parameters

Field Description
id A unique ID per event.
created The date and time of the event in Unix Epoch Time format.
data A Terminal Test Completed object.
type terminal.test.completed
_links lp: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

Field Format Required? Description
terminalProcessId string Mandatory The terminal process ID associated with this test, provided in the synchronous response to the Terminal Test request.
result string Mandatory The 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

Field Format Required? Description
billerId UUID Mandatory HICAPS’s unique reference for the Biller.
terminalId string Mandatory The terminal’s ID, as stored on the terminal.

Sale Body Parameters

Field Format Required? Description
amount decimal (2dp) Mandatory The total sale amount to be processed by the terminal.
invoiceId string Optional If this is a gap payment relating to a previously submitted invoice, the invoiceId should be passed in for reference.
computerName string Optional The Windows computer name identifier for the local workstation the PMS user is using to ensure optimal message routing.

Example Submit Sale Request

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

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

Field Format Required? Description
{onSaleCompleted} URI Mandatory The URI that you provided during onboarding for the terminal.sale.completed event.

Webhook Body Parameters

Field Description
id A unique ID per event.
created The date and time of the event in Unix Epoch Time format.
data A Sale Completed object.
type terminal.sale.completed
_links lp: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

Field Format Required? Description
terminalProcessId string Mandatory The terminal process ID associated with this sale, provided in the synchronous response to the Submit Sale request.
saleId string Conditional The HICAPS reference for the sale.
saleReference string Conditional The terminal’s reference for the sale.
transactionDateTime string
YYYY-MM-DDTHH:mm:ss		 Conditional The date/time stamp provided by the terminal for the transaction.
amount decimal (2dp) Conditional The sub-total amount processed by the terminal, exclusive of any surcharge amount.
surcharge decimal (2dp) Conditional The 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.
responseCode string Conditinoal The transaction status code received by the terminal from the merchant network. See Terminal Response Codes for more info.
responseText string Conditional The 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

Field Format Required? Description
billerId UUID Mandatory HICAPS’s unique reference for the Biller.
terminalId string Mandatory The terminal’s ID, as stored on the terminal.

Refund Body Parameters

Field Format Required? Description
amount decimal (2dp) Mandatory The refund amount.
saleId string Optional If this is a refund relating to a previously submitted sale, the saleId should be passed in for reference.
computerName string Optional The Windows computer name identifier for the local workstation the PMS user is using to ensure optimal message routing.

Example Submit Refund Request

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

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

Field Format Required? Description
{onRefundCompleted} URI Mandatory The URI that you provided during onboarding for the terminal.refund.completed event.

Webhook Body Parameters

Field Description
id A unique ID per event.
created The date and time of the event in Unix Epoch Time format.
data A Refund Completed object.
type terminal.refund.completed
_links lp: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

Field Format Required? Description
terminalProcessId string Mandatory The terminal process ID associated with this refund, provided in the synchronous response to the Submit Refund request.
refundId string Conditional The HICAPS reference for the refund.
refundReference string Conditional The terminal’s reference for the refund.
transactionDateTime string
YYYY-MM-DDTHH:mm:ss		 Conditional The date/time stamp provided by the terminal for the transaction.
amount decimal (2dp) Conditional The total amount processed by the terminal.
surcharge decimal (2dp) Conditional The 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.
responseCode string Conditinoal The transaction status code received by the terminal from the merchant network. See Terminal Response Codes for more info.
responseText string Conditional The 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

Field Format Required? Description
{onTerminalScreenUpdated} URI Mandatory The URI that you provided during onboarding for the terminal.screen.updated event.

Webhook Body Parameters

Field Description
id A unique ID per event.
created The date and time of the event in Unix Epoch Time format.
data A Terminal Screen Updated object.
type terminal.screen.updated
_links lp: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

Field Format Required? Description
terminalProcessId string Mandatory The 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.
screenStatus Screen Status Mandatory The screen status object containing the on-screen message.

Screen Status Parameters

Field Format Required? Description
message string Mandatory The 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 provided these in response to sale, refund, etc. transactions.

Click to expand

Response Code Response Description
00 Approved
01 Refer to card issuer
02 Refer to card issuer
03 Invalid merchant
04 Refer to card issuer
05 Do not honour
06 Transaction timeout
07 Refer to card issuer
08 Approved with signature
09 Submitted for processing
12 Declined
14 Invalid card number
54 Expired card
96 System error
98 MAC error
H1 Timeout waiting for terminal
H2 Timeout waiting for terminal
H3 Timeout waiting for terminal
H6 Terminal busy
BZ Terminal busy
CE Comms error
EN Network request error
HM Hardware error
HW Hardware error
LC Lost carrier
NA Network error
PF Power fail
TO Timeout
TC Cancelled 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:

Environment URI Description
Sandbox https://api.ndis.providers.sandbox.lanternpay.com This is a pre-production environment used for testing.
Production https://api.ndis.providers.lanternpay.com This is the production environment.

Item Category Mapping

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

Prefix Technical Name Friendly Names
01 DAILY_ACTIVITIES Daily Activities
Assistance with daily life
Assistance with daily life (Includes SIL)
02 TRANSPORT Transport
03 CONSUMABLES Consumables
04 SOCIAL_COMMUNITY_CIVIC Assistance with social and community participation
Social Community and Civic Participation
Assistance with Social, Economic and Community Participation
05 ASSISTIVE_TECHNOLOGY Assistive Technology
06 HOME_MODIFICATIONS Home Modifications
Home Modifications and Specialised Disability Accommodation (SDA)
07 SUPPORT_COORDINATION Support Coordination
Coordination of Supports
08 CB_HOME_LIVING CB Home Living
Improved Living Arrangements
09 CB_SOCIAL_COMMUNITY_CIVIC CB Social Community and Civic participants
Increased Social and Community Participation
10 CB_EMPLOYMENT CB Employment
Finding and Keeping a Job
11 CB_RELATIONSHIPS CB Relationships
Improved Relationships
12 CB_HEALTH_WELLBEING CB Health & Wellbeing
Improved Health and Wellbeing
13 CB_LIFELONG_LEARNING CB Lifelong learning
Improved Learning
14 CB_CHOICE_CONTROL CB Choice & Control
Improved Life Choices
15 CB_DAILY_ACTIVITY CB 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

Field Format Required? Description
{ndisMemberNotification} URI Mandatory The URL that you provided for the ndisMemberNotification event.

Webhook Body Parameters

Field Description
id A unique ID per event.
created The date and time of the event in Unix Epoch Time format.
data A Ndis Member Notification object.
type ndis.member.notification
_links lp: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

Field Format Required? Description
eventId string Mandatory This is the Event Id as passed through from the NDIA. Additional information on the different events and their schema can be found here.
response Ndis Member Response Object Mandatory A 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

Field Format Required? Description
participant integer Mandatory The pariticpants NDIS number that the notification relates to. This will be present on all ndis.member.notification webhooks
providerRole string Conditional The role of the Provider e.g. Plan Manager or Support Coordinator
startDate date Conditional The start date of the event in YYYY-MM-DD format
endDate date Conditional The 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 resouece 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

Field Format Required? Description
billerId UUID Mandatory HICAPS’s unique reference for the Biller.
memberNumber string Mandatory Member’s identifier, as issued by the NDIS. Max 10 digits.

Request Plan Type Body Parameters

Field Format Required? Description
surname string Mandatory Member’s surname. Max 80 chars.
dateOfBirth string Mandatory Member’s date of birth in YYYY-MM-DD format.

Example Retrieve a Plan Type Request

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

Retrrieve a Plan Type Response

HTTP 202

Plan Type Retrieved

WEBHOOK → {onPlanTypeRetrieved}

This webhook will trigger once the Plan has been retrieved.

Path Parameters

Field Format Required? Description
{onPlanTypeRetrieved} URI Mandatory The URL that you provided for the onPlanTypeRetrieved event.

Webhook Body Parameters

Field Description
id A unique ID per event.
created The date and time of the event in Unix Epoch Time format.
data A PlanType object.
type ndis.member.planType.retrieved
_links lp: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

Field Format Description
isPacePlan boolean Returns a true value if participant is PACE enabled. Returns false if empty.
planFirstStartDate date The 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

Field Format Required? Description
billerId UUID Mandatory HICAPS’s unique reference for the Biller.
memberNumber string Mandatory Member’s identifier, as issued by the NDIS. Max 10 digits.

Request Plan Body Parameters

Field Format Required? Description
memberNumber string Mandatory Member’s identifier, as issued by the NDIS. Max 10 digits.
surname string Mandatory Member’s surname. Max 80 chars.
dateOfBirth string Mandatory Member’s date of birth in YYYY-MM-DD format.

Example Retrieve a Plan Request

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

Retrrieve a Plan Response

HTTP 202

Plan Retrieved

WEBHOOK → {onPlanRetrieved}

This webhook will trigger once the Plan has been retrieved.

Path Parameters

Field Format Required? Description
{onPlanRetrieved} URI Mandatory The URL that you provided for the onPlanRetrieved event.

Webhook Body Parameters

Field Description
id A unique ID per event.
created The date and time of the event in Unix Epoch Time format.
data An array of Plans.
type ndis.member.plans.retrieved
_links lp: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

Field Format Description
participantPlanId Integer maximum 10 char The indentifier for the plan, numeric, maximum 10 characters
planStartDate date The start date for the plan in YYYY-MM-DD format.
planEndDate date The end date for the plan in YYYY-MM-DD format.
isPacePlan boolean Returns a true value if participant is PACE enabled. Returns false if empty.
planFirstStartDate date The 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 retieve 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

Field Format Required? Description
billerId UUID Mandatory HICAPS’s unique reference for the Biller.
memberNumber string Mandatory Member’s identifier, as issued by the NDIS. Max 10 digits.

Body Parameters

Field Format Required? Description
surname string Mandatory Member’s surname. Max 80 chars.
dateOfBirth date Mandatory Member’s date of birth in YYYY-MM-DD format.

Retrieve Budgets Body Example

{
  "planId": 1080874,
  "surname": "Rogers",
  "dateOfBirth": "2000-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

Field Format Required? Description
{onBudgetRetrieved} URI Mandatory The URL that you provided for the onBudgetRetrieved event.

Webhook Body Parameters

Field Description
id A unique ID per event.
created The date and time of the event in Unix Epoch Time format.
data Provides an array of Budget Information
type ndis.member.budget.retrieved
_links lp: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 Parameters

Field Format Description
instalmentStart date Instalment Start Date in YYYY-MM-DD format
instalmentEnd date Instalment End Date in YYYY-MM-DD format
isPacePlan Boolean Indicates if it’s a PACE plan or not true or false
participantPlanId Integer Maximum 10 char Plan ID for which budget is required. Max Length(10)”
approvedAmount decimal (2dp) The total budget for the specific Support Category (e.g 297.50). Max Length(P14, S2)
spentAmount decimal (2dp) The total spent under the specific Support Category (e.g 0.000). Max Length(P14, S2)
remainingAmount decimal (2dp) The total remaining for the specific Support Category (e.g 297.50). Max Length(P14, S2)
planManagement An Array of Plan Management Budget Parameters An Array of information detailing the budget at the plan management level

Plan Management Budget Parameters

Field Format Description
instalmentStart date Instalment Start Date in YYYY-MM-DD format
instalmentEnd date Instalment End Date in YYYY-MM-DD format
planManagement String Maximum 30 char Plan Management type - Self,Plan or Agency. Max Length(30) e.g. ZCOR_PLAN
planManagementText String Maximum 1333 char Plan Mangement Type Description. Max Length(1333) e.g. Core Plan Managed
approvedAmount decimal (2dp) The total budget for support type. Max Length(P14, S2)
allocatedAmount decimal (2dp) The amount allocated to the Support Type under Service Bookings. Max Length(P14, S2)
spentAmount decimal (2dp) The amount spent under the support type. Max Length(P14, S2
remainingAmount decimal (2dp) The amount remanining under the suport type. Max Length(P14, S2)
suppTypLvlDtls An Array of Support Type Budget Parameters An Array of information detailing the budget at the support type level

Support Type Budget Parameters

Field Format Description
instalmentStart date Instalment Start Date in YYYY-MM-DD format
instalmentEnd date Instalment End Date in YYYY-MM-DD format
supportType String Maximum 30 char Support Type Codes. Max Length(30) e.g. ZCOR
supportTypeText String Maximum 1333 char Support Type Description. Max Length(1333) e.g. Core
approvedAmount decimal (2dp) The total budget for support type. Max Length(P14, S2)
allocatedAmount decimal (2dp) The amount allocated to the Support Type under Service Bookings. Max Length(P14, S2)
spentAmount decimal (2dp) The amount spent under the support type. Max Length(P14, S2
remainingAmount decimal (2dp) The amount remanining under the suport type. Max Length(P14, S2)
suppCatLvlDtls An Array of Support Category Budget Parameters An Array of information detailing the budget at the category level

Support Category Budget Parameters

Field Format Description
instalmentStart date Instalment Start Date in YYYY-MM-DD format
instalmentEnd date Instalment End Date in YYYY-MM-DD format
supportCategory String Maximum 30 char Support Category Code. Max Length(30) e.g. CONSUMABLES
supportCategoryText String Maximum 1333 char Support Category Description. Max Length(1333) e.g. Consumables
approvedAmount decimal (2dp) The total budget for support type. Max Length(P14, S2)
allocatedAmount decimal (2dp) The amount allocated to the Support Type under Service Bookings. Max Length(P14, S2)
spentAmount decimal (2dp) The amount spent under the support type. Max Length(P14, S2
remainingAmount decimal (2dp) The amount remanining under the suport type. Max Length(P14, S2)
suppItmLvlDtls An Array of Support Item Budget Parameters An Array of information detailing the budget at the support item level

Support Item Budget Parameters

Field Format Description
itemType string Max Length 54 Stated, Quoted, In-kind Items. Max Length(54) e.g. ZSGA
item string Max Length 40 Stated, Quoted, In-kind Items. Max Length(40) e.g. 01_003_0107_1_1
approvedAmount decimal (2dp) The total budget for support type. Max Length(P14, S2)
allocatedAmount decimal (2dp) The amount allocated to the Support Type under Service Bookings. Max Length(P14, S2)
spentAmount decimal (2dp) The amount spent under the support type. Max Length(P14, S2
remainingAmount decimal (2dp) The amount remanining under the suport type. Max Length(P14, S2)
quoteableItem Boolean Flag to identify if quote required.
quoteApproved Boolean Flag to identify if quote approved.
inKind Boolean Flag for in-kind item.

Example Budget Retrieved Webhook

{
    "isPacePlan": true,
    "participantPlanId": 0,
    "instalmentStart": "2022-11-11",
    "instalmentEnd": "2025-11-11",
    "approvedAmount": 437000,
    "spentAmount": 0,
    "remainingAmount": 437000,
    "planManagement": [
        {
            "instalmentStart": "2022-11-11",
            "instalmentEnd": "2025-11-11",
            "planManagement": "",
            "planManagementText": "Plan-managed",
            "approvedAmount": 252000,
            "allocatedAmount": 0,
            "spentAmount": 0,
            "remainingAmount": 252000,
            "suppTypLvlDtls": [
                {
                    "supportType": "",
                    "supportTypeText": "Core",
                    "instalmentStart": "2022-11-11",
                    "instalmentEnd": "2025-11-11",
                    "approvedAmount": 252000,
                    "allocatedAmount": 0,
                    "remainingAmount": 252000,
                    "spentAmount": 0,
                    "suppCatLvlDtls": [
                        {
                            "supportCategory": "",
                            "supportCategoryText": "Consumables",
                            "instalmentStart": "2022-11-11",
                            "instalmentEnd": "2025-11-11",
                            "spentAmount": 0,
                            "allocatedAmount": 0,
                            "remainingAmount": 252000,
                            "approvedAmount": 252000,
                            "suppItmLvlDtls": [
                                {
                                    "itemType": "",
                                    "item": "",
                                    "approvedAmount": 0,
                                    "allocatedAmount": 0,
                                    "spentAmount": 0,
                                    "remainingAmount": 0,
                                    "quoteableItem": false,
                                    "quoteApproved": false,
                                    "inKind": false
                                }
                            ]
                        }
                    ]
                }
            ]
        },
        {
            "instalmentStart": "2022-11-11",
            "instalmentEnd": "2025-11-11",
            "planManagement": "",
            "planManagementText": "Plan-managed",
            "approvedAmount": 185000,
            "allocatedAmount": 0,
            "spentAmount": 0,
            "remainingAmount": 185000,
            "suppTypLvlDtls": [
                {
                    "supportType": "",
                    "supportTypeText": "Capital",
                    "instalmentStart": "2022-11-11",
                    "instalmentEnd": "2025-11-11",
                    "approvedAmount": 5000,
                    "allocatedAmount": 0,
                    "remainingAmount": 5000,
                    "spentAmount": 0,
                    "suppCatLvlDtls": [
                        {
                            "supportCategory": "",
                            "supportCategoryText": "Home Modifications",
                            "instalmentStart": "2022-11-11",
                            "instalmentEnd": "2025-11-11",
                            "spentAmount": 0,
                            "allocatedAmount": 0,
                            "remainingAmount": 5000,
                            "approvedAmount": 5000,
                            "suppItmLvlDtls": [
                                {
                                    "itemType": "",
                                    "item": "",
                                    "approvedAmount": 0,
                                    "allocatedAmount": 0,
                                    "spentAmount": 0,
                                    "remainingAmount": 0,
                                    "quoteableItem": false,
                                    "quoteApproved": false,
                                    "inKind": false
                                }
                            ]
                        }
                    ]
                },
                {
                    "supportType": "",
                    "supportTypeText": "Capacity Building",
                    "instalmentStart": "2022-11-11",
                    "instalmentEnd": "2025-11-11",
                    "approvedAmount": 180000,
                    "allocatedAmount": 0,
                    "remainingAmount": 180000,
                    "spentAmount": 0,
                    "suppCatLvlDtls": [
                        {
                            "supportCategory": "",
                            "supportCategoryText": "Improved Daily Living Skills",
                            "instalmentStart": "2022-11-11",
                            "instalmentEnd": "2025-11-11",
                            "spentAmount": 0,
                            "allocatedAmount": 0,
                            "remainingAmount": 180000,
                            "approvedAmount": 180000,
                            "suppItmLvlDtls": [
                                {
                                    "itemType": "",
                                    "item": "",
                                    "approvedAmount": 0,
                                    "allocatedAmount": 0,
                                    "spentAmount": 0,
                                    "remainingAmount": 0,
                                    "quoteableItem": false,
                                    "quoteApproved": false,
                                    "inKind": false
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}

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

Field Format Required? Description
billerId UUID Mandatory HICAPS’s unique reference for the Biller.
memberNumber string Mandatory Member’s identifier, as issued by the NDIS. Max 10 digits.

Service Booking Body Parameters

Field Format Required? Description
memberNumber string Mandatory Member’s identifier, as issued by the NDIS. Max 10 digits.
surname string Mandatory Member’s surname. Max 80 chars.
dateOfBirth string Mandatory Member’s date of birth in YYYY-MM-DD format.
bookingType string Mandatory Must be ZSAG for a standard agency booking or ZPLM for Plan Managed Service bookings.
startDate string Mandatory Start date in YYYY-MM-DD format.
endDate string Mandatory End date in YYYY-MM-DD format.
planId integer Mandatory The member’s plan ID. Max 10 digits.
providerComments string Optional Any provider comments to be added to the service booking.
items Array of Service Booking Items Mandatory The list of categories and items available for this service booking.

Service Booking Items Parameters

Field Format Required? Description
itemCategory string Mandatory The item category that is claimable.
itemCode string Optional The 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.
quantity integer Mandatory The quantity of items on the service booking.
unitPrice decimal (2dp) Mandatory The 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

Field Format Required? Description
{onServiceBookingCreated} URI Mandatory The URL that you provided for the onServiceBookingCreated event.

Webhook Body Parameters

Field Description
id A unique ID per event.
created The date and time of the event in Unix Epoch Time format.
data A single Service Booking object.
type ndis.member.serviceBooking.created
_links lp: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

Field Format Required? Description
billerId UUID Mandatory HICAPS’s unique reference for the Biller.
memberNumber string Mandatory Member’s identifier, as issued by the NDIS. Max 10 digits.
serviceBookingNumber integer Mandatory Service booking reference, as issued by the NDIS. Max 10 digits.

Edit a Service Booking Body Parameters

Field Format Required? Description
itemCategory string Mandatory This must be a valid NDIS category.
itemCode string Mandatory This must be a valid NDIS item code.
bookingType string Optional ZSAG or ZPLM, must match the booking type.
quantity number Optional The quantity of unitPrice you wish to set the service booking to (must adhere to price guide limits).
unitPrice number Mandatory The 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

Field Format Required? Description
billerId UUID Mandatory HICAPS’s unique reference for the Biller.
memberNumber string Mandatory Member’s identifier, as issued by the NDIS. Max 10 digits.
serviceBookingNumber integer Mandatory Service booking reference, as issued by the NDIS. Max 10 digits.

Extend a Service Booking Body Parameters

Field Format Required? Description
bookingType string Mandatory ZSAG or ZPLM, must match the booking type.
endDate string Mandatory The 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

Field Format Required? Description
{onServiceBookingEdited} URI Mandatory The URL that you provided for the onServiceBookingEdited event.

Webhook Body Parameters

Field Description
id A unique ID per event.
created The date and time of the event in Unix Epoch Time format.
data serviceBookings array containing Service Booking objects.
type ndis.member.serviceBooking.edited
_links lp: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 templted URI to POST to in order to subscribe to all service booking changes for a member.
lp:service-booking-updates-unsubscribe defines the templted 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

Field Format Required? Description
billerId UUID Mandatory HICAPS’s unique reference for the Biller.
memberNumber string Mandatory Member’s identifier, as issued by the NDIS. Max 10 digits.
serviceBookingNumber integer Mandatory Service 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 delection of a service booking has completed.

Path Parameters

Field Format Required? Description
{onServiceBookingDeleted} URI Mandatory The URL that you provided for the onServiceBookingDeleted event.

Webhook Body Parameters

Field Description
id A unique ID per event.
created The date and time of the event in Unix Epoch Time format.
data Confirms the service booking number of the service booking that was deleted.
type ndis.member.serviceBooking.deleted
_links lp: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 templted URI to POST to in order to subscribe to all service booking changes for a member.
lp:service-booking-updates-unsubscribe defines the templted 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 resources allows retrieval of a specific service booking.

Path Parameters

Field Format Required? Description
billerId UUID Mandatory HICAPS’s unique reference for the Biller.
memberNumber string Mandatory Member’s identifier, as issued by the NDIS. Max 10 digits.
serviceBookingNumber integer Mandatory Service 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

Field Format Required? Description
{onServiceBookingRetrieved} URI Mandatory The URL that you provided for the onServiceBookingRetrieved event.

Webhook Body Parameters

Field Description
id A unique ID per event.
created The date and time of the event in Unix Epoch Time format.
data A single Service Booking object.
type ndis.member.serviceBooking.retrieved
_links lp: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

Field Format Required? Description
id integer Mandatory The service booking reference, as issued by the NDIS. Max 10 digits.
type string Mandatory The service booking type
memberNumber string Mandatory The member number, as issued by the NDIS. Max 10 digits.
memberName string Mandatory The member’s full name.
startDate date
YYYY-MM-DD		 Mandatory The start date of the service booking.
endDate date
YYYY-MM-DD		 Mandatory The end date of the service booking.
revisedEndDate date
YYYY-MM-DD		 Mandatory The new service booking end date, if changed.
inkindProgram boolean Mandatory
status string Mandatory The current status of the service booking.
Values include: Approved, Rejected, Deleted, Awaiting Provider Approval, etc.
virtualStatus string Mandatory Indicates whether the service booking is Active or Inactive.
planId integer Mandatory The member’s plan reference, as issued by the NDIS. Max 10 digits.
providerComments string Mandatory Any comments associated with the service booking.
items Array of Service Booking Items Mandatory All items associated with the service booking.

Service Booking Items

Field Format Required? Description
itemCategory string Mandatory The item’s category.
itemCode string Mandatory The item’s code.
itemDescription string Mandatory The item’s description.
quantity integer Mandatory The quantity of this item on the service booking.
allocatedAmount decimal (2dp) Mandatory The total amount of funds allocated to this item for this service booking.
remainingAmount decimal (2dp) Mandatory The 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 resources 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

Field Format Required? Description
billerId UUID Mandatory HICAPS’s unique reference for the Biller.
memberNumber string Mandatory Member’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

Field Format Required? Description
{onServiceBookingsRetrieved} URI Mandatory The URL that you provided for the onServiceBookingsRetrieved event.

Webhook Body Parameters

Field Description
id A unique ID per event.
created The date and time of the event in Unix Epoch Time format.
data serviceBookings array containing Service Booking objects.
type ndis.member.serviceBookings.retrieved
_links lp: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 templted URI to POST to in order to subscribe to all service booking changes for a member.
lp:service-booking-updates-unsubscribe defines the templted 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

Field Format Required? Description
{onServiceBookingUpdated} URI Mandatory The URL that you provided for the onServiceBookingUpdated event.

Webhook Body Parameters

Field Description
id A unique ID per event.
created The date and time of the event in Unix Epoch Time format.
data serviceBooking object containing Service Booking Detail View data.
type ndis.member.serviceBooking.updated
_links lp: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 pariticpant. 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

Field Format Required? Description
billerId UUID Mandatory HICAPS’s unique reference for the Biller.
memberNumber string Mandatory Member’s identifier, as issued by the NDIS. Max 10 digits.

Body Parameters

Field Format Required? Description
tenantId string Optional This 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

Field Format Required? Description
{onMemberSubscribed} URI Mandatory The URL that you provided for the onMemberSubscribed event.

Webhook Body Parameters

Field Description
id A unique ID per event.
created The date and time of the event in Unix Epoch Time format.
data Confirms the member number for the member whose service bookings have been subscribed to.
type ndis.member.serviceBookingUpdates.subscribed
_links lp: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

Field Format Required? Description
billerId UUID Mandatory HICAPS’s unique reference for the Biller.
memberNumber string Mandatory Member’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

Field Format Required? Description
{onMemberUnsubscribed} URI Mandatory The URL that you provided for the onMemberUnsubscribed event.

Webhook Body Parameters

Field Description
id A unique ID per event.
created The date and time of the event in Unix Epoch Time format.
data Confirms the member number for the member whose service bookings subscriptions have been removed.
type ndis.member.serviceBookingUpdates.unsubscribed
_links lp: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

Field Format Required? Description
billerId UUID Mandatory HICAPS’s unique reference for the Biller.
memberNumber string Mandatory Member’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

Field Format Required? Description
{onSubscribedMembersRetrieved} URI Mandatory The URL that you provided for the onSubscribedMembersRetrieved event.

Webhook Body Parameters

Field Description
id A unique ID per event.
created The date and time of the event in Unix Epoch Time format.
data subscribedMembers array containing each member number with an active subscription to service booking updates.
type ndis.member.activeSubscriptions.retrieved
_links lp: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"
        }
    }
}