Provider API

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

Overview

The Provider API integrates LanternPay 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 LanternPay 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 scheme, is the entity adjudicating the invoices. The program represents the funding body of a claim.

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

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

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.

LanternPay 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 LanternPay 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 except 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

Predetermination requests are “what if” simulations to help the user to create valid invoices and avoid rejections. Predeterminations are similar in concept to a quote, but they are not binding nor guaranteed and no payments are made from predeterminations.

Predeterminations can be sent to a program as an invoice is being created as long as there’s at least one claim on the invoice. Additional predeterminations can be sent as each new claim is added to the invoice, line item by line item, so the user is getting feedback from the program as they’re creating the invoice which can be very useful for picking up a range of issues that may result in an invoice being rejected by the program, without having to wait for a full invoice to be created and submitted.

For example, if an invoice has three claim lines on it then there could be three separate predeterminations sent to the program:

  1. Predetermination 1: showing invoice header data + the first line item
  2. Predetermination 2: showing invoice header data + the first line item + the second line item
  3. Predetermination 3: showing invoice header data + the first line item + the second line item + the third line item

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

Some examples of claiming issues that predeterminations are designed to prevent are things like incorrect member data, invalid provider data, un-claimable items for a member’s plan and can also be used to check how much funding a program will provide for given items, for example when comparing a generic brand drug with a name brand drug.

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 LanternPay. 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 LanternPay 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 LanternPay 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 LanternPay. LanternPay then sends all claims to the program for adjudication. Once the program has adjudicated on the claim they send an update back to LanternPay. LanternPay 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 LanternPay.

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 LanternPay payment process. Generally speaking LanternPay manages the payment process on behalf of the program, but this may not be the case for every program - see below.

For LanternPay managed payments, a single payment is made to each biller, per program, per day. Once the program has completed it’s adjudication on all claim line items on an invoice then a payment is created and queued in our payment processor for that biller for that program (called the biller’s “payment bucket”). Throughout the day, as other invoices for this biller are approved more payments are created and added to the bucket.

At the end of the day, all payments in the bucket are aggregated and a payment instruction is created by LanternPay on behalf of the program. This payment instruction contains the net amount of all invoices approved for that biller for that day for that program and then sent to the bank for payment.

For example, if a biller has claimed in a single day:

  • 3x WSV invoices for $10, $20 & $35, and
  • 2x TAC invoices for $15 & $30

Then that biller will receive two payments: one for $65 from WSV and one for $45 from TAC. LanternPay will email a remittance advice (PDF) and associated bank reconciliation data (CSV) for these payments to the biller’s nominated email address.

Additionally, LanternPay 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-LanternPay managed payments, where the program pays the biller directly, LanternPay usually will not trigger a Invoice Payment Status Updated webhook for these invoices because the program has managed the payment without LanternPay involvement. There are some cases where the program will tell LanternPay about the payment they’ve made, in which case we will trigger this webhook to advise the user.

Programs that have non-LanternPay managed payments:

  • NDIS and NDIS Agency - note, for NDIS Agency claims the NDIS tells LanternPay about the payment when it’s made so we will trigger the payment status updated webhook to advise the user.
  • Medicare
  • Medibank Private
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 now supports integration with HICAPS terminals for payments, e.g. a gap or ad-hoc payment. This functionality includes support for the existing VX terminal and the new Trinity terminal being rolled out to market. Additional features relating to member verification and claiming functionality (including Medicare Easy Claim) coming online soon.

Payment functionality available:

  1. Send a payment request to a nominated terminal and receive transaction results - including surcharging if applicable
  2. Send a refund request to a nominated terminal and receive transaction results
  3. Receive real time updates from the terminal showing what is on-screen for visualisation/rendering in your application

See the Terminals API specifications for detailed view on the Terminals API functionality.

Currently (as at March, 2023), all integrated HICAPS terminals continue to require the installation of the HICAPS Connect application (see here External Link) on a local workstation to facilitate communication between the terminal and the Provider API. However, coming in in 2024, the Trinity terminal’s direct-to-web capability will be rolled out removing the need for HICAPS Connect to be installed on a local workstation - the Trinity terminal will communicate directly with HICAPS Digital’s cloud service that your PMS will integrate with, via this Provider API. No changes will be required by your PMS to support this updated functionality.

Technical Overview

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

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

  • authroization_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 LanternPay 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 LanternPay 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 LanternPay portal, and you can embed the LanternPay login screen within your application so the user never has to leave your application to authorize your platform on the LanternPay Provider API.

This is the high level flow:

  1. The user is prompted to connect to LanternPay
  2. Your application redirects the user to our identity service login page
  3. The user logs into our identity server which automatically authorises 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 LanternPay 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 LanternPay 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

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 5 minutes in sandbox and can be used repeatedly within this time frame.
    • There is data inside the token which you need to store against the user, for example the billerId which is required as part of most API functions. You should always verify if a LanternPay 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. Additionally, the token expiry (exp) is noted in unix epoch time so you can ensure a new token is retrieved before the current token expires.
  • refresh_token - you will store this non-JWT formatted token against the user and use this token to retrieve a new id_token once the id_token has expired.
    • The refresh_token lasts 365 days in production and 1 hour in sandbox and can be used repeatedly within this time frame to retrieve new id_tokens.
    • We recommend using the refresh token to retrieve a new id_token around 2-5mins before the id_token expires to ensure no permission errors.
    • Once the refresh_token expires, the user must re-authroize your platform with LanternPay’s identity service.
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 LanternPay portal and storing them securely in your application. Whenever the user wants to perform an API action, you will retrieve a security token from LanternPay’s identity service for the user and pass that in the API call to LanternPay.

This is the high level flow (assumes the user has already copied their LanternPay 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

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 5 minutes in sandbox and can be used repeatedly within this time frame.
    • There is data inside the token which you need to store against the user, for example the billerId which is required as part of most API functions. You should always verify if a LanternPay 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. Additionally, the token expiry (exp) is noted in unix epoch time so you can ensure a new token is retrieved before the current token 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 initial security tokens after user authorization

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

LanternPay 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 LanternPay 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 LanternPay 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 LanternPay 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
  • LanternPay 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 LanternPay 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 LanternPay APIs are asynchronous. LanternPay 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.

Standard Payload

The standard API response body for GET operations is:

{
    "...data...",
    "_links": {
        "self": {
            "href": "{uri}"
        },
        "lp:ref": {
            "href": "{uri}"
        }
    }
}

API Response Codes

The LanternPay 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
  • LanternPay has accepted the request and will action.
  • LanternPay 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
  • LanternPay 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": "claimStatus[0].claimId",
            "reason": "Claim Id Unknown"
        },
        {
            "name": "claimStatus[2].status",
            "reason": "Status 'MyStatus' is unknown.  Status must be one of 'Authorized', 'Rejected'."
        }
    ]
}

Webhooks

Webhooks allow LanternPay to signal to the user that an event has occurred within the LanternPay platform. During onboarding, you will define API endpoints that LanternPay 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.
LanternPay 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 LanternPay 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 next 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-API-Key: 1234
  • OAuth 2.0 Authorization: Webhook subscriber can configure OAuth details. LanternPay 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

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 LanternPay attempts to deliver a webhook. LanternPay actions for each status code are as below.

Status Code LanternPay 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 LanternPay Support Staff to investigate.
5xx Server Error
  • Timeout has occurred.
  • Retry the webhook (see retry policy below).
  • If all retries fail, notify LanternPay 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 LanternPay 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 LanternPay 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.

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 LanternPay’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 LanternPay 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",
                                "itemCode": "PSY23131",
                                "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 LanternPay’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 LanternPay’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.
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.
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 Medicare Referral Conditional These fields are required for some Medicare claims.
medicareDva Medicare DVA Conditional These fields are required for Medicare DVA claims.
ndis NDIS Conditional These fields are required for customers who have access to the NDIS Payee module
wcq WCQ Conditional These fields are required for WorkCover QLD claims

Medicare Invoice Parameters

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

Medicare Referral Parameters

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

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

Medicare Referral Provider Parameters

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

Medicare DVA Parameters

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

Medicare DVA Disability Parameters

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

NDIS Invoice Parameters

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

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

NDIS Payee Invoice Parameters

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

WCQ Invoice Parameters

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

Claims Parameters

Field Format Required? Description
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.
unitPrice decimal (4 dp) Conditional The price for each unit of the product or service. This price is tax inclusive when tax is applicable.
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. 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.

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.

Click to expand

  • Accommodation
  • Acupuncturist
  • Advanced Dental Technician
  • Ambulance
  • Audiologist
  • Chiropodist/Podiatrist
  • Chiropractor
  • Complimentary Therapist
  • Dental Prosthetist
  • Dentist
  • Dietitian/Nutritionist
  • Doctor
  • Domestic Service Provider
  • Driving Instructor
  • Equipment Supplier
  • Exercise Physiology
  • Interpreting Service
  • Lifestyle Retailer
  • Massage Therapy
  • Medical Non-GP/Specialist
  • Myotherapy
  • Naturopaths
  • Nurse
  • Nurse Practitioner
  • Occupational Therapist
  • Optical Dispensary
  • Optometrist
  • Orthoptist
  • Osteopath
  • Pathologist
  • Pharmacy
  • Physical Educator
  • Physiotherapist
  • Podiatrist
  • Psychologist
  • Radiologist
  • Social Worker
  • Speech Therapist
  • Sports Complex/Gym
  • Transport
  • Vocational Provider

ItemCustomFields Parameters

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

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

NDIS Parameters

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

NDIS ABN Values

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

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

Medicare Claim Parameters

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

General Medical Parameters

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

Pharmacy Parameters

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

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

{
    "billerInvoiceId": "HAYA20200871",
    "program": "mpl",
    "responsePriority": "normal",
    "created": "2020-01-30T03:49:25.548+00:00",
    "invoiceNumber": "INV-ID-01",
    "invoiceDate": "2020-01-30",
    "member": {
        "memberNumber": "123413123",
        "givenName": "Genesis",
        "familyName": "Mason",
        "birthDate": "1990-04-01",
        "gender": "male",
        "email": "some-email@example.com"
    },
    "claims": [
        {
            "billerClaimId": "CLM-ID-01",
            "provider": {
                "person": {
                    "givenName": "Jane",
                    "familyName": "Doe"
                },
                "organization": {
                    "facilityName": "My Pharmacy"
                },
                "registrations": {
                    "ahpraRegistrationNumber": null,
                    "medicareProviderNumber": null,
                    "medibankProviderNumber": "424242"
                },
                "contactPoint": {
                    "phone": null,
                    "fax": null,
                    "email": "my-pharmacy@example.com",
                    "pager": null,
                    "url": null,
                    "sms": null,
                    "other": null
                },
                "discipline": "pharmacy"
            },
            "itemPublisher": "fred",
            "itemCode": "Painkiller-0001",
            "itemCustomFields": {
                "pharmacy": {
                    "scriptNumber": "1234",
                    "prescribingDoctorName": "John Smith"
                }
            },
            "patient": null,
            "serviceDate": null,
            "serviceDateTime": null,
            "servicePeriod": {
                "start": "2020-01-30T02:49:25.630+00:00",
                "end": "2020-01-30T03:49:25.630+00:00"
            },
            "location": {
                "address": {
                    "lines": [
                        "Plaza 1, 1st Street",
                        "CBD"
                    ],
                    "city": "Sydney",
                    "postalCode": "2000",
                    "state": "NSW",
                    "country": null
                },
                "position": null
            },
            "consentReceived": true,
            "consentAuthority": "Pharmacy",
            "quantity": 1.1034,
            "unitPrice": 42.7853,
            "taxCode": "GST",
            "description": "Some panadol",
            "contractNumber": "CONTRACT-001",
            "contractLineItemNumber": "CONTRACT-ITEM-001"
        }
    ]
}

Example Submit Invoice Response - Medibank

{
  "invoiceId": "72f5dca0-be8a-4469-b349-25a4e2cc9463",
  "claims": [
    {
      "claimId": "8f637f02-6ed7-44f4-af2f-ad9106487190",
      "billerClaimId": "CLM-ID-01"
    }
  ]
}

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 LanternPay’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 LanternPay 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 LanternPay.
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 LanternPay’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 LanternPay’s reference to this claim.
billerClaimId String Conditional Invoice line item identifier from the user’s application, eg. PMS.
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 10 chars (any longer chars will be ignored).
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",
        "itemCode": "PSY23131",
        "benefit": 120,
        "adjudications": [
          {
            "amount": 106,
            "reason": "Standard package"
          },
          {
            "amount": 14,
            "reason": "Bonus loyalty"
          }
        ],
        "state": "approved"
      },
      {
        "claimId": "4d01ce18-bb10-4390-af84-3a2c56e2dc44",
        "billerClaimId ": "2",
        "itemCode": "PSY23453",
        "benefit": 0,
        "adjudications": [
          {
            "amount": 0,
            "reason": "Item not applicable for xxxxx..."
          }
        ],
        "state": "rejected"
      },
      {
        "claimId": "68e1a679-a455-4726-b52d-d467c7f2d1f5",
        "billerClaimId ": "3",
        "itemCode": "PSY2115",
        "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 LanternPay 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.

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

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 LanternPay’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 LanternPay.
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",
        "itemCode": "04_197_0104_6_1",
        "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",
        "itemCode": "01_001_0101_1_1",
        "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",
        "itemCode": "01_001_0101_1_1",
        "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 claim types only.

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"
}

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 requestId is passed back so you can match this webhook to the original verification request.
status object follows the structure of Member Verification Status
_links lp:webhook-error defines the URI to POST in case the webhook needs to be replayed by LanternPay.
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.
updatedAt dateTime
YYYY-MM-DDTHH:mm:ss.SSS±HH:mm		 Conditional The date/time when the member’s status was last updated with the Program.
member Member Object Conditional Same structure as Member Parameters, including memberCustomFields
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.
actions Array of Actions Conditional An optional list of actions the user can take if there are issues with the member’s status with the program.

Example Member Verification Updated Webhook

{
    "id": "d76eac52-6b7f-4303-8c70-91ae2f4313f9",
    "created": 1565140165,
    "data": {
        "requestId": "abveac52-6b7f-4303-8c70-91ae2f431333",
        "status": {
            "state": "verified",
            "statusTitle": "Program Approved",
            "statusDescription": "This patient is eligible to claim for Medicare",
            "updatedAt": "2021-12-12T12:12:12.000+10:00",
            "member": {
                "memberNumber": "123413123",
                "givenName": "Genesis",
                "familyName": "Mason",
                "birthDate": "1990-04-01",
                "gender": "male",
                "email": "test@test.com",
                "memberCustomFields": {
                    "personIdentifier": "1"
                }
            },
            "invalidParams": null,
            "actions": [
                {
                    "title": "Please fill out this form",
                    "description": "You need to fill out this form first before you proceed",
                    "class": "info",
                    "href": "https://www.lanternpay.com"
                }
            ]
        },
        "type": "member.verification.updated",
        "_links": {
            "lp:webhook-error": {
                "href": null
            }
        }
    }
}

Items

This resources exposes the LanternPay 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 modality, 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.

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 LanternPay’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 LanternPay’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 LanternPay’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 LanternPay’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 LanternPay. 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.
successful boolean Mandatory Whether the terminal test was successful or not.

Example Terminal Test Completed Webhook

{
    "id": "0a2a42f5-30c9-4310-a6dc-1820067f3d18",
    "created": 1675729223,
    "data": {
        "terminalProcessId": "e63286a9-b155-4438-989e-a12020094663",
        "successful": true
    },
    "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 LanternPay’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.

Example Submit Sale Request

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

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 LanternPay. 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 LanternPay 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 total amount processed by the terminal, inclusive of any surcharge amount.
surcharge decimal (2dp) Conditional The surcharge amount added by the terminal, if applicable.
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 LanternPay’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.

Example Submit Refund Request

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

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

Plans

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

Retrieve Plan Type

POST /billers/{billerId}/members/{memberNumber}/plans/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 LanternPay’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 LanternPay. 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 LanternPay’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 LanternPay. 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.
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,
                "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

Participant with Existing Plan

This API will allow Plan Managers to retrieve a participant’s plan managed budget details. Existing participant migrated to PACE should use current NDIS number

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

  • An active Standard Service Booking for the Support Category of CB Choice and Control first exists with Support Items of either 14_033_0127_8_3 or 14_034_0127_8_3.
  • An active Plan Managed Service Booking exists between the participant and your organisation.
  • Received the participant’s consent to view their budget details , via the Participant Portal.
  • Plan Id is required

Participant with PACE Plan

This API will allow Plan Managers to retrieve a participant’s plan managed budget details. 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.
  • Plan ID not required

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 LanternPay’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
planId integer Optional Members Plan Id, max 10 digits. Not required for PACE participants.
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 LanternPay. 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 LanternPay’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 LanternPay. 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 LanternPay’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 LanternPay’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 LanternPay. 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 LanternPay’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 LanternPay. 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 LanternPay’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 LanternPay. 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 LanternPay’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 LanternPay. 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 LanternPay. 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 LanternPay’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 LanternPay. 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 LanternPay’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 LanternPay. 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 LanternPay’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 LanternPay. 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"
        }
    }
}