Provider API

Alert This is the specification for our current Provider API, 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 system at the point of sale (e.g. using a Practice Management System) to send invoices to the program and receive adjudication results in real-time. Payment information of approved invoices that will be settled by LanternPay overnight can then also flow directly to the Provider’s accounting system 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

LanternPay distinguishes between the entity providing the service (Provider) and the entity submitting an invoice (Biller). An organization Provider (eg 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.

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 Further Information
ndis National Disability Insurance Scheme https://www.ndis.gov.au External Link
tac Transport Accident Commission https://www.tac.vic.gov.au External Link
mpl Medibank Private Limited https://www.medibank.com.au External Link
pga-fluvax Pharmacy Guild of Australia - Fluvax Program https://www.guild.org.au External Link

Billers

A biller is the entity making the claim and receiving payment.

Providers

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

Invoices and Claims

An Invoice is a representation of the invoice data submitted. The Invoice contains a collection of Claims, which represent the claim line items in the Invoice.

Predeterminations

Predetermination requests (also known as a ‘quote’) are ‘what if’ simulations to help the user to create valid invoices and avoid rejections. Predetermination responses are the best bets provided directly by the program, but they are not binding nor guaranteed.

See Predeterminations for more information.

States vs Statuses

States

A claim can only be in one of the states defined by LanternPay. For example, a claim will move through states: pendingapprovedpaid. The state primarily determines the types of actions that are allowed at this point in time and/or tells the user what would be the next expected actions a program will take. For example, if a claim is in the approved state, LanternPay will not allow the user to attempt to resubmit that claim and the user can expect the next action is for the claim to be paid.

Note that the state can be considered LanternPay’s cached version of the last known state of that object within the program (i.e. the program is the master of the state).

The states are either changed by the program or LanternPay (usually to a pending state whilst awaiting a response from the program). See Claiming Processes for more information on the claim submission flow.

Statuses

Status fields, including claim.statusTitle and claim.statusDescription are available as part of the responses to add more information to the claim. These statuses are provided by the program and can include free text and a link to assist the user in successfully submitting their claim. Example values of these fields include:

  • claim.statusTitle = “Pending Report”
  • claim.statusDescription = “Please complete the online form at https://forms.exampleorg.com/12345

Claiming Process

The user submits an invoice (list of claims) to LanternPay. LanternPay then sends all claims to the program to adjudicate and give a response on. LanternPay then notifies the user through a webhook with the updated status on the claims.

Provider API Claiming Process Diagram

Claim States

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

Provider API Claim States Diagram

Claim State Definitions

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 but requires 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.
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) or submit a new, valid, claim.
APPROVED approved The claim is approved and will be paid to the value of the specified benefit, which might be a full or partial funding amount. Biller expects to be paid in the next payment run to the value of the specified benefit
PAID paid The claim is paid to the specified benefit Biller expects the specified benefit to have been included in a recent payment to their bank account (within banking timeframes)
AWAITING CANCEL RESPONSE awaitingCancelResponse The biller has asked to cancel this claim, awaiting confirmation from Program that it is cancelled. Biller may wait for a short while to see if the cancellation is approved. They expect an update when the cancellation is confirmed.
CANCEL PENDING cancelPending The program has received the cancellation request but is not able to process it automatically. Program will send another update soon. Biller is aware that the cancellation request has been received and is being processed.
CANCELLED cancelled Program has processed the cancelation request and cancelled the claim in their system. Depends on the context:
  1. If payment has not been made yet, Biller expects to not be paid for this claim.
  2. If payment has been made, Biller may have to return funds to the program (process may vary by Program)
PAYMENT FAILED paymentFailed The payment for the claim has failed Biller expects to be contacted about how to rectify the payment details.

Technical Overview

API Authentication

LanternPay’s Provider API supports two authentication options:

  • Basic Authorization:
    • LanternPay provides a Client Id and Client Secret - these should be formed into a Basic Authorization header as the username and password respectively
  • OAuth 2.0
    • LanternPay provides an Oauth 2.0 Identity Provider endpoint which supports authorization_code and client_credentials grant types.

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

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 program that an event has occurred within the LanternPay platform. During initial configuration, the program will specify the endpoint and authentication credentials for each webhook (some of which are optional).

Field Description
id A unique ID per event. This allows the program to perform de-duplication in the event that the same event is signalled more than once.
LanternPay may sent the same event multiple times if it fails to get positive acknowledgement of a request.
created The date and time in Unix Epoch Time of the event.
data A block of data relevant to the event. The schema of the data block will vary for given webhook types.
Typically, the data block will contain both data properties and action properties, which will contain the URI of the possible 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 (similar to HAL, see below) 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
  • Basic Authorization: Webhook subscriber can configure a basic authorization username and password which will be included in the Authorization header as the as Basic header with the value computed to be the base64 encoding of the %username%:%password% string
  • 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 program webhook handler should handle the request asynchronously.

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

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

Webhook Response Codes

The webhook handler may respond with one of the following HTTP Status Codes. 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 with a server error or a timeout, LanternPay will retry the webhook:

  • First-Level Retry (FLR):
    • 5 times in rapid succession - to resolve in case of intermittent failure
  • Second-Level Retry (SLR):
    • If all FLRs fail, LanternPay will fall back to SLR
    • 3 times with an increasing delay between each SLR attempt - 10s, 20s, 30s
    • Each attempt will undergo a fresh FLR of 5 retries

Each retried attempt 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.

API Resources

Base URIs

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

All URIs in the sections below are relative to the above base URIs.

Root

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

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

Claims Parameters

Field Format Required? Description
billerClaimId String Conditional Invoice line item identifier from the PMS. This field should be unique for each invoice.
provider Provider Conditional Provider is the entity (person/organisation) who performed the work. Required by some Programs.
itemPublisher string Mandatory 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.
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, FRE.
description string Conditional Description of the item or service.
contractNumber string Conditional The contract that this claim is claimed against.
contractLineItemNumber string Conditional The contract line item that this claim is claimed against.

Provider Parameters

Field Format Required? Description
providerProgramIdentifier string Conditional The program’s unique identifier for this provider.
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 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.

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 a Provider’s 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
  • Occupational Therapist
  • Optical Dispensary
  • Optometrist
  • Orthoptist
  • Osteopath
  • Pharmacy
  • Physical Educator
  • Physiotherapist
  • Psychologist
  • 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
Pharmacy Pharmacy Conditional This field is conditional for pharmacy claims.

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.

Patient Parameters

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

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 Required, if no position defined.
position Position Conditional Required, if no address defined. GPS position WGS84.

Address Parameters

Field Format Required? Description
lines an array of string Mandatory Each line of the street address.
city string Mandatory
postalCode string Mandatory
state string Mandatory
country string Conditional

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

{
  "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 user can request a cancellation of an invoice, which has to be accepted by LanternPay and the program. Invoices can be cancelled subject to payment state the program supporting this cancellation. The PMS can send a cancellation request, and then will receive a webhook with the updated invoice status. When the cancellation request is not accepted the invoice status will remain unchanged.

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 Status Updated

WEBHOOK {onInvoiceStatusUpdated}

Path Parameters

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

Webhook Body Parameters

Field Description
id A unique ID per event.
created The data and time in Unix Epoch Time of the event.
type claiming.invoice.updated
data Schema follows the structure of an InvoiceStatus
_links lp:webhook-error defines the URI to POST in case the webhook needs to be retried by LanternPay.
Note: this value can be null if no retry is possible. See example webhook.

InvoiceStatus Parameters

Field Format Required? Description
invoiceId UUID Mandatory LanternPay’s reference to the claim.
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.

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 system, eg. PMS.
benefit decimal Mandatory The amount that will be paid by the program for this invoice item.
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: noChange,provisionallyApproved, approved, rejected. These values are described in the Claim State table. If excluded, defaults to noChange.
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 vs Statuses. 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%”.

Sample Invoice Status Updated Webhook - TAC

{
  "id": "d76eac52-6b7f-4303-8c70-91ae2f4313f9",
  "created": 1565140165,
  "data": {
    "invoiceId": "d5e6e8f7-bc9c-4a5b-8c60-8e8ffd665e26",
    "created": "2019-06-12T12:41:12:222+10:00",
    "claims": [
      {
        "claimId": "4d01ce18-bb10-4390-af84-3a2c56e2dc44",
        "billerClaimId ": 1,
        "itemCode": "PSY23131",
        "benefit": 120,
        "adjudications": [
          {
            "amount": 20,
            "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
    }
  }
}

Sample Invoice Status Updated Webhook - NDIS

{
  "id": "d76eac52-6b7f-4303-8c70-91ae2f4313f9",
  "created": 1565140165,
  "data": {
    "invoiceId": "d5e6e8f7-bc9c-4a5b-8c60-8e8ffd665e26",
    "created": "2019-06-12T12:41:12:222",
    "claims": [
      {
        "claimId": "4d01ce18-bb10-4390-af84-3a2c56e2dc44",
        "billerClaimId ": 1,
        "itemCode": "04_197_0104_6_1",
        "benefit": 0,
        "adjudications": [
          {
            "amount": 0,
            "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 ": 2,
        "itemCode": "01_001_0101_1_1",
        "benefit": 200,
        "adjudications": [
          {
            "amount": 150,
            "reason": "Standard Package"
          },
          {
            "amount": 30,
            "reason": "Bonus loyalty"
          }
        ],
        "state": "approved"
      },
      {
        "claimId": "f17f52aa-e92b-4673-4ae3-bb4d7280f748",
        "billerClaimId ": 3,
        "itemCode": "01_001_0101_1_1",
        "benefit": 24,
        "adjudications": [
          {
            "reason": "Paid at reduced rate. Please contact the NDIS."
          }
        ],
        "state": "approved"
      }
    ]
  },
  "type": "claiming.invoice.updated",
  "_links": {
    "lp:webhook-error":
    {
      "href": null
    }
  }
}

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 data and time in Unix Epoch Time of the event.
type claiming.predetermination.updated
data Schema follows the structure of an InvoiceStatus
_links lp:webhook-error defines the URI to POST in case the webhook needs to be retried by LanternPay.
Note: this value can be null if no retry 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",
    "claims": [
      {
        "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": 30.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

When supported by the program, LanternPay can facilitate a member eligibility check prior to claim submission.

Check Member Eligibility

POST /members/eligibility

Member Parameters

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

MemberCustomFields Parameters

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

Example Function

Example code here

Member Eligibility Status

WEBHOOK {onMemberEligibilityStatus}

Path Parameters

Field Description
onMemberEligibilityStatus The URI you provided for the onMemberEligibilityStatus event.

Webhook Body Parameters

Field Description
id A unique ID per event.
created The data and time in Unix Epoch Time of the event.
type
data Schema follows the structure of a Member Eligibility Status, as defined below.
_links

Member Eligibility Status Parameters

Field Format Required? Description
memberNumber string Mandatory The program’s reference for this member.
program string Mandatory The name of the program that provided the provider state.
state enum Mandatory Values include: non-eligible, eligible, pending, unknown. This is the updated state of the Member from the program’s perspective.
statusTitle string Conditional Describes the Provider’s status with this program.
statusDescription string Conditional Describes the reason for the status with this program.

Example Function

Example code here

Contracts

Create Contract

POST billers/{billerId}/contract

Path Parameters

Field Format Required? Description
billerId UUID Mandatory LanternPay’s unique reference of the Biller.

Body Parameters

Field Format Required? Description
billerContractId string Conditional A reference to the contract determined by the Biller.
created dateTime
YYYY-MM-DDTHH:mm:ss.SSS±HH:mm
Mandatory dateTime of creation of this entity in the PMS.
program string Mandatory The program that the contract is for.
member Member Conditional Member who is receiving the good or service.
contractLineItems Array of ContractLineItem Conditional An array of contract line items.

Contract Line Item Parameters

Field Format Required? Description
billerContractLineItemId string Conditional A unique reference to the contract line item determined by the Biller.
provider Provider Conditional Provider who is providing the good or service in the contract.
itemCode string Conditional The identifier of the item that will be associated in this contract.
startDate date Conditional The start date of the contract.
endDate date Conditional The end date of the contract.
quantity decimal 4dp Conditional The quantity of service or item that has been agreed to in the initial contract.
unitPrice decimal 4dp Conditional The unit price per item or per service.
freeText string Conditional Free text to describe the contract.

Example Contract Requested

Example code here

Contract Status

WEBHOOK {onContractStatusUpdated}

Path Parameters

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

Body Parameters

Field Format Required? Description
contractId UUID Mandatory LanternPay’s reference to the contract. Use this Id when doing a GET contract.
billerContractId string Conditional A reference to the contract determined by the Biller.
contractLineItemStatus Array of ContractLineItemStatus Mandatory An array of the outcome for each contract line item.

Contract Line Item Status Parameters

Field Format Required? Description
contractLineItemId UUID Mandatory LanternPay’s reference to the contract line item.
billerContractLineItemId string Conditional A reference to the contract line item determined by the Biller.
state enum Conditional Values include: noChange, approved, rejected.

Example Contract Status Updated Webhook

Example code here

Get a Contract

GET contracts/{contractId}

Path Parameters

Field Format Required? Description
contractId UUID Mandatory LanternPay’s reference to the contract

Contract Body Parameters

Field Format Required? Description
contractId UUID Mandatory LanternPay’s reference to the contract.
billerContractId string Conditional A reference to the contract determined by the Biller.
created dateTime
YYYY-MM-DDTHH:mm:ss.SSS±HH:mm
Mandatory dateTime of creation of this entity in the PMS.
program string Mandatory The program that the contract is for.
member Member Conditional Member who is receiving the good or service.
contractLineItems Array of ContractLineItem Conditional An array of contract line items.

Contract Line Item Parameters

Field Format Required? Description
contractLineItemId UUID Mandatory LanternPay’s reference to the contract line item.
billerContractLineItemId string Conditional A unique reference to the contract line item determined by the Biller.
provider Provider Conditional Provider who is providing the good or service in the contract.
itemCode string Conditional The identifier of the item that will be associated in this contract.
startDate date Conditional The start date of the contract.
endDate date Conditional The end date of the contract.
quantity decimal 4dp Conditional The quantity of service or item that has been agreed to in the initial contract.
quantityRemaining decimal 4dp Conditional The quantity of service or item remaining in the contract.
unitPrice decimal 4dp Conditional The unit price per item or per service.
freeText string Conditional Free text to describe the contract.
state enum Conditional Values include: noChange, approved, rejected.

Example Get a Contract Response

Example code here

Get a Member’s Contracts

GET member/memberNumber/contacts

Retrieves a list of contracts of a member.

Note: this is using memberNumber (program’s ref of a person). Should it be per program, per member? What if multuple programs use a specific registration as the memberNumber, like the medicareNumber as an identifier? Then the member is not uniquely identified and may not pick up all contracts that they have?

Path Parameters

Field Format Required? Description
memberId UUID Mandatory LanternPay’s reference to the member.

Body Parameters

Field Format Required? Description
contracts Array of Contracts.

Example Get a Member’s Contracts Status

Example code here