Plan Manager API

Overview

The following documentation details the Plan Manager API for LanternPay Integration Partners servicing NDIS Plan Managers. This will allow plan managers, via our Integration Partners, to submit invoices to the NDIS on behalf of their participants for approval and funding which LanternPay will disburse to the relevant service provider. Additionally, the Plan Manager API will also allow Plan Managers the ability to review and approve/reject claims submitted directly to LanternPay by registered service providers.

Invoices and Claims

An invoice is a representation of the invoice data submitted by a plan manager. The invoice contains a collection of claims, which represent the line items on the invoice. The NDIS processes claims, not invoices, so an invoice can contain claims which have individual funding decisions.

Claims can have a number of statuses which are described below and are applied to each claim individually. Through the Plan Manager API, a plan manager can lookup an invoice and see an invoice-level status as well as claim-level statuses, as defined below.

Invoice and Claim Statuses

Level	Status	Description
Invoice	Draft	This is a draft invoice state which has not been submitted for processing. Used to validate claims before submitting an invoice for processing.
Invoice	Submitted	This is the state of an invoice submitted directly to LanternPay by a Provider and at least one claim is awaiting Authorization by a Plan Manager. See claim states for further detail.
Invoice	Processed	This is the state of an invoice submitted via the Plan Manager API and has been processed successfully by LanternPay. See claim states for further detail.
Claim	AuthorizationRequired	This claim was submitted directly to LanternPay by a provider and is awaiting plan manager approval before further processing of the claim will occur.
Claim	Authorized	This claim has been authorized by LanternPay or a plan manager, but not yet by the NDIS.
Claim	AuthorizedByProgram	This claim has been authorized by the NDIS and will be paid. See Invoice and Claim Funding below for further detail.
Claim	Rejected	This claim has been rejected by LanternPay upon initial validation or by a plan manager. See `insufficientContributionReason` on the claim for the rejection reason.
Claim	RejectedByProgram	This claim has been rejected by the NDIS and will not be paid. See `insufficientContributionReason` on the claim for the rejection reason.
Claim	Cancelled	This claim has been cancelled and will not be processed further.

Invoice and Claim Funding

As the NDIS will sometimes pay above or below a claimed amount (e.g. a rounding discrepancy) we provide the below funding information at the invoice and claim level via the Plan Manager API to enable reconciliation of NDIS payments.

At the invoice level:

the totalClaimAmount field is the total value of all claims on the invoice and represents the total amount of funds requested from the NDIS.
the funded field is the total value of all claims where the NDIS has provided funding. If all claims are paid in full then the totalClaimAmount will equal the funded amount.

At the claim level:

the totalClaimAmount field is the amount of funding requested from the NDIS for an individual claim.
the funded field is the amount the NDIS actually paid, which could be equal to, above or under the totalClaimAmount.

See the Get an Invoice section for an example of these fields.

NDIS References

When a claim has been submitted to the NDIS, the claims unique ndisReference field will be populated in the Get an Invoice API response. This reference matches what is shown in the NDIS portal for that claim and is useful when searching for a LanternPay submitted claim (for cancellations, for example)

Additionally, the ndisReference is also shown on the Get a List of Payments API response.

Authentication

All Plan Manager API requests to LanternPay require authentication using basicAuth. LanternPay will provide Sandbox and Production credentials, an API_Key and API_Secret, during onboarding.

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

Additionally, LanternPay will post webhooks on some events which must be configured with authentication via a custom HTTP header. This header contains a webhook header name and value - for example: x-api-key = 123456789. This allows you to verify that the webhook came from LanternPay - you will need to provide this webhook header name and value to LanternPay during onboarding of each plan manager.

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. The following webhooks are currently implemented by LanternPay, you can find more detailed information about these webhooks in the the relevant API resources section:

Webhook	Purpose
onPlanChanged	This webhook is used to flag that a member has been onboarded or a plan has been updated.
Invoice Webhooks	Multiple webhooks that convey the state of an invoice as it travels through it’s lifecycle.
onPaymentScheduled	This webhook is triggered once per day, per planamanager, when a payment file is generated and sent to the bank.
onStatementGenerated	This webhook is used when LanternPay generates a statement for a participant.

All LanternPay webhooks follow a consistent pattern and will generally contain:

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

Webhook Standard Payload

Each webhook will have the following standard payload:

{
    "id": "{uuid}",
    "created": "{unix epoch time}",
    "data": "{data object}",
    "type": "{event type name}",
}

Webhook Authentication

LanternPay webhooks use Custom Http Header for aithentication. The 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

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)² 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

API Resources

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

Base URIs

All URIs in the API Resources section below are relative to these base URIs:

Environment	URI	Description
Sandbox	`https://api.planmanagers.sandbox.lanternpay.com`	This is a pre-production environment you can use for testing.
Production	`https://api.planmanagers.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 follow the lp:get-planmanager link relation to retrieve your plan manager resource. This resource can also be used to ensure the Plan Manager API is online.

Get the API Root

GET /

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

Example Get Root Response

{
    "_links": {
        "self": {
            "href": "https://api.sandbox.lanternpay.com/"
        },
        "lp:get-planmanager": {
            "href": "https://api.sandbox.lanternpay.com/planmanagers/{planManagerKey}",
            "templated": true
        },
        "curies": {
            "name": "lp",
            "href": "https://docs.lanternpay.com/reference#{rel}",
            "templated": true
        }
    }
}

Plan Managers

Plan managers are provided a unique planManagerKey when onboarding with LanternPay allowing them to uniquely manage their participants. Integration partners will be provided with a template for onboarding new plan managers during initial integration.

Get a Plan Manager

GET /planmanagers/{planManagerKey}

The Plan Manager resource contains information about the Plan Manager’s organisation. The _links property contains a list of hypermedia operations available to the plan manager, including lp:add-member and lp:get-member.

Path Parameters

Field	Format	Required?	Description
planManagerKey	UUID	Mandatory	This will be given to you by LanternPay.

Example Get Plan Manager Response

{
    "_links": {
        "self": {
            "href": "https://api.sandbox.lanternpay.com/planmanagers/430b0abf-18ac-0205-3ad5-4bb4dc9659d5"
        },
        "lp:add-member": {
            "href": "https://api.sandbox.lanternpay.com/planmanagers/430b0abf-18ac-0205-3ad5-4bb4dc9659d5/members"
        },
        "lp:get-member": {
            "href": "https://api.sandbox.lanternpay.com/planmanagers/430b0abf-18ac-0205-3ad5-4bb4dc9659d5/members/{membershipNumber}{?programCode}",
            "templated": true
        },
        "lp:add-biller": {
            "href": "https://api.sandbox.lanternpay.com/affiliates/430b0abf-18ac-0205-3ad5-4bb4dc9659d5/billers"
        },
        "curies": {
            "name": "lp",
            "href": "https://docs.lanternpay.com/reference#{rel}",
            "templated": true
        }
    },
    "name": "Plan Manager Inc",
    "planManagerKey": "430b0abf-18ac-0205-3ad5-4bb4dc9659d5",
    "programs": [
        {
            "code": "ndis",
            "shortName": "NDIS",
            "longName": "National Disability Insurance Scheme",
            "membershipNumber": "123456789"
        }
    ]
}

Members

Members (i.e. participants) of the NDIS are managed by plan managers and registered with LanternPay to allow the plan manager to request funding from the NDIS on behalf of the participant. Each member has a unique memberKey and each of the member’s plans has a unique planKey which is used for various functions described below.

Add a Member

POST /planmanagers/{planManagerKey}/members

This resource can be used to create a member (i.e. participant) against the NDIS program. This is an async task and LanternPay will trigger a webhook to the URI provided in the _webhooks object when the member creation is complete. This webhook will also be triggered if the member’s details change in the future, such as plan balances, allowing you to keep your system in sync with LanternPay.

Path Parameters

Field	Format	Required?	Description
planManagerKey	UUID	Mandatory	This will be given to you by LanternPay.

Body Parameters

Field	Format	Required?	Description
membershipNumber	string	Mandatory	The membership number of the member with the program. For example, with an NDIS participant this would be the NDIS number.
programCode	string	Mandatory	The LanternPay code for the program. For example, `NDIS`.
dateOfBirth	YYYY-MM-DD	Mandatory	The member’s date of birth.
name	object	Mandatory	The container object for the member’s name. See table below.
plan	object	Mandatory	The container object for the member’s plan. See table below.
_webhooks	object	Mandatory	The container object for URIs to POST events to. See table below.

Name Object Parameters

Field	Format	Required?	Description
first	string	Mandatory	The member’s first name.
last	string	Mandatory	The member’s last name.

Plan Object Parameters

Field	Format	Required?	Description
priceGuideCode	string	Mandatory	The price guide code for the NDIS member. Valid price guide codes are: `ACT_NSW_QLD_VIC` `NT_SA_TAS_WA` `Remote` `VeryRemote`

_webhooks Object Parameters

Field	Format	Required?	Description
onPlanChangedUri	URI	Mandatory	The URI for LanternPay post to on a member created or changed event. This URI can include query parameters.

Example Add Member Request

{
    "membershipNumber":"123456789",
    "programCode":"ndis",
    "dateOfBirth":"1950-10-01",
    "name":{
        "first":"Sam",
        "last":"Smith"
    },
    "plan":{
        "priceGuideCode":"Remote"
    },
    "_webhooks":{
        "onPlanChanged":"https://webhook.site/0171a369-4934-4fd0-bbd1-f6f26d2a0619"
    }
}

Example Add Member Response

This is a HTTP 202 response verifying that LanternPay has received your request. The onPlanChanged webhook will be triggered once the member setup is complete.

{
    "_links": {
        "self": {
            "href": "https://api.sandbox.lanternpay.com/planmanagers/430b0abf-18ac-0205-3ad5-4bb4dc9659d5/members/232282425?programCode=ndis"
        },
        "curies": {
            "name": "lp",
            "href": "https://docs.lanternpay.com/reference#{rel}",
            "templated": true
        }
    }
}

onPlanChanged Webhook

WEBHOOK {onPlanChangedUri}

This webhook will trigger when a member is activated or when the member’s details change, such as name changes or plan changes. This action tells you something has changed and you should do a GET on the member using the URI in the webhook. The URI we trigger the webhook to is the URI you provided in the Add Member request.

Path Parameters

Field	Format	Required?	Description
onPlanChangedUri	URI	Mandatory	The URI you provided for the `_webhooks.onPlanChanged` field when you created the member.

Body Parameters

Field	Format	Required?	Description
id	UUID	Mandatory	A unique ID for the event.
created	Unix Epoch Time	Mandatory	The date and time in Unix Epoch Time of the event.
data	object	Mandatory	The container object for the webhook data. See table below.
type	string	Mandatory	The event type that triggered the webhook.

Data Object Parameters

Field	Format	Required?	Description
membershipNumber	string	Mandatory	The NDIS membership number of the member.
programCode	string	Mandatory	The LanternPay code for the program. For example, `NDIS`.
memberUri	URI	Mandatory	The link to the member resource.
planUri	URI	Mandatory	The link to the member’s plan resource.

Example onPlanChanged Webhook

{
    "id": "437ec6ab-cda3-465b-90f2-3865d992440b",
    "created": 1518405650.882,
    "data": {
        "membershipNumber": "988028707",
        "programCode": "ndis",
        "memberUri": "https://api.sandbox.lanternpay.com/planmanagers/430b0abf-18ac-0205-3ad5-4bb4dc9659d5/members/988028707?programCode=ndis",
        "planUri": "https://api.sandbox.lanternpay.com/plans/89b8bf06-2bc6-4e98-9f6e-845e5dded24a"
    },
    "type": "planmanagement.member.planchanged"
}

Get a Member

GET /planmanagers/{planManagerKey}/members/{membershipNumber}?programCode={programCode}

This resource can be used to query a member, including summary of their plan information. Links are included in the response to query all the details of the member’s plan(s).

Path Parameters

Field	Format	Required?	Description
planManagerKey	UUID	Mandatory	This will be given to you by LanternPay
membershipNumber	string	Mandatory	The membership number of the member with the program. For example, with an NDIS participant this would be the NDIS number.

Query Parameters

Field	Format	Required?	Description
programCode	string	Mandatory	The LanternPay code for the program. For example, `NDIS`.

Example Get a Member Response

The plan key (UUID) in the response can be used for other queries - see Plans section for more detail.

    "_links": {
        "self": {
            "href": "https://api.sandbox.lanternpay.com/planmanagers/711fd7a1-357e-04e4-03f2-b0d5bfe68562/members/420459861?programCode=ndis"
        },
        "lp:add-biller": {
            "href": "https://api.sandbox.lanternpay.com/members/0460d6cc-637b-4641-b9aa-089510451740/billers"
        },
        "lp:create-invoice": {
            "href": "https://api.sandbox.lanternpay.com/members/0460d6cc-637b-4641-b9aa-089510451740/invoices"
        },
        "lp:create-payee-invoice": {
            "href": "https://api.sandbox.lanternpay.com/planmanagers/711fd7a1-357e-04e4-03f2-b0d5bfe68562/members/0460d6cc-637b-4641-b9aa-089510451740/invoices"
        },
        "lp:validate-contract": {
            "href": "https://api.sandbox.lanternpay.com/members/0460d6cc-637b-4641-b9aa-089510451740/contracts/validate"
        },
        "lp:list-contracts": {
            "href": "https://api.sandbox.lanternpay.com/members/0460d6cc-637b-4641-b9aa-089510451740/contracts"
        },
        "lp:list-billers": {
            "href": "https://api.sandbox.lanternpay.com/members/0460d6cc-637b-4641-b9aa-089510451740/billers"
        },
        "lp:most-used-items": {
            "href": "https://api.sandbox.lanternpay.com/members/0460d6cc-637b-4641-b9aa-089510451740/itemusages"
        },
        "curies": {
            "name": "lp",
            "href": "https://docs.lanternpay.com/reference#{rel}",
            "templated": true
        }
    },
    "_embedded": {
        "lp:plans": [
            {
                "_links": {
                    "self": {
                        "href": "https://api.sandbox.lanternpay.com/plans/a7958bd5-d2c0-4e5d-9b91-e16f55f38f19"
                    },
                    "lp:transaction-history": {
                        "href": "https://api.sandbox.lanternpay.com/plans/a7958bd5-d2c0-4e5d-9b91-e16f55f38f19/transactions{?fromDate,toDate}",
                        "templated": true
                    },
                    "lp:search-items": {
                        "href": "https://api.sandbox.lanternpay.com/plans/a7958bd5-d2c0-4e5d-9b91-e16f55f38f19/items{?query,page}",
                        "templated": true
                    },
                    "lp:invoice-history": {
                        "href": "https://api.sandbox.lanternpay.com/plans/a7958bd5-d2c0-4e5d-9b91-e16f55f38f19/invoices{?fromDate,toDate}",
                        "templated": true
                    }
                },
                "endDate": "2022-12-31",
                "startDate": "2020-01-01",
                "isActive": true,
                "programCode": "ndis",
                "totalBudget": {
                    "total": 12000,
                    "spent": 0,
                    "unspent": 12000,
                    "assigned": {
                        "total": 0,
                        "spent": 0,
                        "unspent": 0
                    },
                    "unassigned": 12000
                }
            }
        ]
    },
    "programs": [
        {
            "code": "ndis",
            "shortName": "NDIS",
            "longName": "National Disability Insurance Scheme"
        }
    ],
    "memberKey": "0460d6cc-637b-4641-b9aa-089510451740",
    "name": {
        "first": "NDIS-416-S3",
        "last": "420459861"
    },
    "membershipNumber": "420459861",
    "dateOfBirth": "1990-01-01"
}

Billers

A biller is an entity that will be receiving funds for services provided to a member. The service provider may be the same entity or a different entity. For example, a medical centre (i.e. the biller) might be an entity collecting funds on behalf of a pharmacist (i.e. the service provider)

LanternPay has two types of billers: a registered biller and an unregistered biller (known as a payee):

A registered biller is a biller that has registered directly with LanternPay and has had all their details verified by LanternPay. Registered billers can submit their invoices directly to LanternPay for any program we support (e.g. NDIS, TAC, etc) and LanternPay will route and process their invoices appropriately. Plan Managers cannot submit invoices on behalf of a registered biller, however, they can refer a biller to LanternPay via the Plan Manager API who would like to register. See Add a Registered Biller, below.
An unregistered biller, or a payee, is a biller that does not have a direct relationship with LanternPay. These billers have a relationship with a plan manager/participant and LanternPay will make payments to these billers by instruction from the plan manager. When the plan manager submits an invoice to LanternPay for a payee the payee details are contained within each invoice. See Create an Invoice, below.

Add a Registered Biller

POST /affiliates/{affiliateKey}/billers

Use this resource to refer an unregistered biller to LanternPay for registration. This will allow them to submit invoices directly to LanternPay for processing to any program LanternPay supports. This is an a-synchronous process as LanternPay must verify the biller’s details to complete registration. See onBillerRegistered webhook below for more detail.

Path Parameters

Field	Format	Required?	Description
affiliateKey	UUID	Mandatory	This is the same as your plan manager key, provided by LanternPay.

Body Parameters

Field	Format	Required?	Description
affiliateBillerNumber	string	Optional	An optional affiliate reference for the biller being referred to LanternPay.
user	object	Mandatory	The container object for the biller’s personal details. See table below.
organization	object	Mandatory	The container object for the biller’s organisational details. See table below.
payment	object	Mandatory	The container object for the biller’s payment details. See table below.
billingAddress	object	Mandatory	The container object for the biller’s billing address. See table below.
_webhooks	object	Mandatory	The container object for URIs to POST events to. See table below.

User Object Parameters

Field	Format	Required?	Description
email	string	Mandatory	The biller’s email.
firstName	string	Mandatory	The biller’s first name.
lastName	string	Mandatory	The biller’s last name.
phoneNumber	10 digits	Mandatory	The biller’s phone number.

Organization Object Parameters

Field	Format	Required?	Description
abn	string	Mandatory	The biller’s ABN.
tradingName	string	Mandatory	The biller’s trading name.
registeredName	string	Mandatory	The biller’s registered business name.

Payment Object Parameters

Field	Format	Required?	Description
bsb	6 digits	Mandatory	The 6 digit BSB for the biller’s bank account.
accountNumber	6 to 9 digits	Mandatory	The biller’s bank account number.
accountName	string	Mandatory	The biller’s bank account name.
emailForRemittance	string	Mandatory	The biller’s email that remittance advices will be sent to.

billingAddress Object Parameters

Field	Format	Required?	Description
unit	string	Optional	The unit or apartment number.
street	string	Mandatory	The street name.
postcode	4 digits	Mandatory	The post code.
state	string	Mandatory	The state or territory code. For example, valid Australian codes are: `QLD`,`NSW`,`ACT`,`VIC`,`TAS`,`NT`,`SA`,`WA`
country	string	Mandatory	The country name.

_webhooks Object Parameters

Field	Format	Required?	Description
onBillerRegistered	URI	Mandatory	The URI for LanternPay post to on the biller registered event. This URI can include query parameters.

Example Add a Registered Biller Request

{
    "affiliateBillerNumber":"123456789",
    "user":{
        "email":"some@email.com",
        "firstName":"Sam",
        "lastName":"Smith",
        "phoneNumber":"0412345678"
    },
    "organization":{
        "abn":"12345678901",
        "tradingName":"Sam's Trucks",
        "registeredName":"Sam's Trucks"
    },
    "payment":{
        "bsb":"012345",
        "accountNumber":"123456789",
        "accountName":"My Bank Account",
        "emailForRemittance":"Sam.Smith@lanternpay.com"
    },
    "billingAddress":{
        "unit":"Unit 1",
        "street":"742 Evergreen Terrace",
        "postcode":"2000",
        "state":"NSW",
        "country":"Australia"
    },
    "_webhooks":{
        "onBillerRegistered":"https://somedomain.com/biller-registered"
    }
}

Example Add a Registered Biller Response

This is a HTTP 202 response verifying that LanternPay has received your request. The onBillerRegistered webhook will be triggered once the registered biller setup is complete.

Accepted

onBillerRegistered Webhook

WEBHOOK {onBillerRegisteredUri}

This webhook will trigger when a biller has completed registration.

Path Parameters

Field	Format	Required?	Description
onBillerRegisteredUri	URI	Mandatory	The URI you provided for the `_webhooks.onBillerRegistered` field when you created the registered biller.

Body Parameters

Field	Format	Required?	Description
id	UUID	Mandatory	A unique ID for the event.
created	Unix Epoch Time	Mandatory	The date and time in Unix Epoch Time the webhook was triggered.
data	object	Mandatory	The container object for the webhook data. See table below.
type	string	Mandatory	The event type that triggered the webhook.

Data Object Parameters

Field	Format	Required?	Description
affiliateBillerNumber	string	Mandatory	The affiliate reference for the biller if provided during the Add a Registered Biller API request.
programCode	string	Mandatory	The LanternPay code for the program. For example, `NDIS`.
billerKey	UUID	Mandatory	The LanternPay unique key for the biller.

Example onBillerRegistered Webhook

{
    "id": "437ec6ab-cda3-456b-90f2-3865d992440b",
    "created": 1518405650.883, 
    "data": {
        "affiliateBillerNumber": "123456789",
        "programCode": "ndis",
        "billerKey": "486ec6ab-csc3-495b-90z2-3865d775440b"
    },
    "type": "billers.biller.registered",
}

Get a Registered Biller

GET /billers/{billerKey}

Use this resource to query a biller you have referred for registration to LanternPay.

Field	Format	Required?	Description
billerKey	UUID	Mandatory	The LanternPay unique key for the biller provided in the `onBillerRegistered` webhook.

Example Get a Biller Response

{
    "_links": {
        "self": {
            "href": "https://api.sandbox.lanternpay.com/billers/48cf5266-3ea3-040e-3b3a-f2d355c28a87"
        },
        "curies": {
            "name": "lp",
            "href": "https://docs.lanternpay.com/reference#{rel}",
            "templated": true
        }
    },
    "billerKey": "48cf5266-3ea3-040e-3b3a-f2d355c28a87",
    "name": "Sam's Physio",
    "email": "some@email.com",
    "abn": "12345678901",
    "billingAddress": null,
    "isRegistered": false
}

Plans

A plan is a collection of service bookings containing items, budgets and date ranges for a member. Each plan has a unique planKey which can be queried via the API to view a detailed breakdown of the plan.

Get a Plan

GET /plans/{planKey}

Use this resource to query a member’s plan details. This contains individual plan coverages, dates and budgets which can be updated periodically. If you receive the onPlanChanged member webhook, detailed above, you should query the member’s details as well as the plan details for that member.

Path Parameters

Field	Format	Required?	Description
planKey	UUID	Mandatory	The plan key for the member returned in the `lp:links` `_links:self` section of the Get a Member response.

Example Get a Plan Response

Note: under budget the assigned field represents funds that are reserved (including total, spent and unspent) under a contract - see Contracts for more information.

{
    "_links": {
        "self": {
            "href": "https://api.sandbox.lanternpay.com/plans/a7958bd5-d2c0-4e5d-9b91-e16f55f38f19"
        },
        "curies": {
            "name": "lp",
            "href": "https://docs.lanternpay.com/reference#{rel}",
            "templated": true
        }
    },
    "membershipNumber": "420459861",
    "programName": "NDIS",
    "coverages": [
        {
            "category": {
                "name": "Assistance with Daily Life (CORE)",
                "code": "0001"
            },
            "statedItem": null,
            "startDate": "2020-01-01",
            "endDate": "2022-12-31",
            "initialBudget": 9000,
            "budget": {
                "total": 9000,
                "spent": 0,
                "unspent": 9000,
                "assigned": {
                    "total": 0,
                    "spent": 0,
                    "unspent": 0
                },
                "unassigned": 9000
            },
            "programCoverageNumber": "92001000"
        },
        {
            "category": {
                "name": "Assistance with Daily Life (CORE)",
                "code": "0001"
            },
            "statedItem": {
                "code": "01_001_0101_1_1",
                "name": "Transitional Support"
            },
            "startDate": "2020-01-20",
            "endDate": "2022-02-20",
            "initialBudget": 3000,
            "budget": {
                "total": 3000,
                "spent": 0,
                "unspent": 3000,
                "assigned": {
                    "total": 0,
                    "spent": 0,
                    "unspent": 0
                },
                "unassigned": 3000
            },
            "programCoverageNumber": "92001000"
        }
    ],
    "totalFlexBudget": {
        "total": 0,
        "spent": 0,
        "unspent": 0,
        "assigned": {
            "total": 0,
            "spent": 0,
            "unspent": 0
        },
        "unassigned": 0
    },
    "totalBudget": {
        "total": 12000,
        "spent": 0,
        "unspent": 12000,
        "assigned": {
            "total": 0,
            "spent": 0,
            "unspent": 0
        },
        "unassigned": 12000
    },
    "totalStatedBudget": {
        "total": 12000,
        "spent": 0,
        "unspent": 12000,
        "assigned": {
            "total": 0,
            "spent": 0,
            "unspent": 0
        },
        "unassigned": 12000
    }
}

Get Plan Invoice History

GET /plans/{planKey}/invoices?fromDate={fromDate}&toDate={toDate}

Use this API endpoint to retrieve a list of all invoices within a specific plan’s date range. Note, this API will not return draft invoices.

Path Parameters

Field	Format	Required?	Description
planKey	UUID	Mandatory	The plan key returned in the Get a Member response in the `lp:links` `_links:self` section.

Query Parameters

Field	Format	Required?	Description
fromDate	YYYY-MM-DD	Mandatory	The first date in the search range.
toDate	YYYY-MM-DD	Mandatory	The last date in the search range.

Example Get Plan Invoice History Response

{
    "_links": {
        "self": {
            "href": "https://api.sandbox.lanternpay.com/plans/7810d904-1bce-41a9-9090-4cbca40b65d4/invoices?fromDate=2019-01-01&amp;toDate=2019-03-01"
        },
        "curies": {
            "name": "lp",
            "href": "https://docs.lanternpay.com/reference#{rel}",
            "templated": true
        }
    },
    "_embedded": {
        "lp:invoices": [
            {
                "_links": {
                    "self": {
                        "href": "https://api.sandbox.lanternpay.com/invoices/31724c23-e780-4632-b98f-16b10312ab40"
                    }
                },
                "invoiceKey": "31724c23-e780-4632-b98f-16b10312ab40",
                "submittedDate": "2019-02-06T00:00:00",
                "invoiceDate": "2019-02-06T00:00:00",
                "invoiceNumber": "227609015",
                "total": 50,
                "totalFunded": 50,
                "biller": {
                    "billerKey": "48cf5266-3ea3-040e-3b3a-f2d355c28a87",
                    "name": "Sam's Physio"
                }
            },
            {
                "_links": {
                    "self": {
                        "href": "https://api.sandbox.lanternpay.com/invoices/13926cb0-d712-4896-9576-cfb4b9254468"
                    }
                },
                "invoiceKey": "13926cb0-d712-4896-9576-cfb4b9254468",
                "submittedDate": "2019-02-06T00:00:00",
                "invoiceDate": "2019-02-06T00:00:00",
                "invoiceNumber": "233805794",
                "total": 50,
                "totalFunded": 50,
                "biller": {
                    "billerKey": "48cf5266-3ea3-040e-3b3a-f2d355c28a87",
                    "name": "Sam's Physio"
                }
            }
        ]
    }
}

Plan Statements

A plan statement is a monthly record of activity on a given participant’s plan - similar to a bank statement. LanternPay will generate a PDF plan statement for any active plan for a participant at the start of every month for the previous month’s activity. This means that a given participant may get multiple statements generated per month, if there was activity on multiple plans in that month.

The most common examples of this are:

the participant’s plan expires mid-month and a new plan is created and there is activity (claiming) on both during the month
a claim is raised against an expired plan that is still eligible for claiming

LanternPay will then securely deliver this statement via the Plan Manager API to the integration partner. From there, the integration partner can choose how they share the plan statement with their plan managers and participants.

onStatementGenerated

WEBHOOK {onStatementGeneratedUri}

This webhook indicates that the PDF generation process has completed and the plan statement resource is ready for download via the API.

This webhook will trigger once per active plan, per participant, per month. This means that any given participant may receive multiple webhooks if multiple statements are generated for that participant, as described above.

Path Parameters

Field	Format	Required?	Description
onStatementGeneratedUri	URI	Mandatory	The URI, per plan manager, you provided to LanternPay during onboarding.

Body Parameters

Field	Format	Required?	Description
id	UUID	Mandatory	A unqiue ID for the event.
created	Unix Epoch Time	Mandatory	The date and time in Unix Epoch Time the webhook was triggered.
data	object	Mandatory	The container object for the webhook data. See table below.
type	string	Mandatory	The event that triggered the webhook.

Data Object Parameters

Field	Format	Required?	Description
membershipNumber	Member Number	Mandatory	The NDIS member number.
planManagerKey	UUID	Mandatory	The plan manager this member belongs to.
planKey	UUID	Mandatory	The plan key this statement is for.
statementKey	UUID	Mandatory	The unique key for this statement.
planUri	URI	Mandatory	The link to the plan this statement is for.
statementUri	URI	Mandatory	The link to the plan statement resource. Performing a `GET` on this resource will generated a download link with a very short expiry that will allow you to download the statement PDF. See below.
statementPeriod	Object	Mandatory	This object contains the plan statement `startDate` and `endDate` in `YYYY-MM-DD` format.

Example onStatementGenerated Webhook

{
    "id": "7363d2d4-0999-401a-8d31-3b9d96bba404",
    "created": 1583219144,
    "data": {
        "membershipNumber": "123456789",
        "planManagerKey": "e0217e84-58ba-4294-a1cf-c86d287c8de1",
        "planKey": "08029b72-2db3-4b8a-9210-e4fb227e95b0",
        "statementKey": "d3291120-2604-429b-b66b-950e55bf52e8",
        "planUri": "https://api.sandbox.lanternpay.com/plans/08029b72-2db3-4b8a-9210-e4fb227e95b0",
        "statementUri": "https://api.sandbox.lanternpay.com/plans/08029b72-2db3-4b8a-9210-e4fb227e95b0/statements/d3291120-2604-429b-b66b-950e55bf52e8",
        "statementPeriod": {
            "startDate": "2020-01-01",
            "endDate": "2020-01-31"
        },
    },
    "type": "planmanagement.member.statementgenerated"
}

Get a Plan Statement

GET /plans/{planKey}/statement/{statementKey}

This resource URI will return the lp:download-statement link relation which contains a temporary download link to a specific plan statement PDF. This resource URI can be stored and used at any time to generate a new lp:download-statement temporary download link.

Note: The temporary download link contained in the lp:download-statement link relation will expire in 30 seconds and can be up to 2,000 characters in length.

Path Parameters

Field	Format	Required?	Description
planKey	UUID	Mandatory	The plan key for the member included in the `onStatementGenerated` webhook.
statementKey	UUID	Mandatory	The plan statement key provided in the `onStatementGenerated` webhook.

Example Get a Plan Statement Request

{
    "_links": {
        "self": {
            "href": "https://api.sandbox.lanternpay.com/plans/08029b72-2db3-4b8a-9210-e4fb227e95b0/statements/d3291120-2604-429b-b66b-950e55bf52e8"
        },
        "lp:download-statement": {
            "href": "{the temporary download link}"
        },
        "lp:plan": {
            "href": "https://api.sandbox.lanternpay.com/plans/08029b72-2db3-4b8a-9210-e4fb227e95b0"
        },
        "curies": {
            "name": "lp",
            "href": "https://docs.lanternpay.com/reference#{rel}",
            "templated": true
        }
    },
    "planKey": "08029b72-2db3-4b8a-9210-e4fb227e95b0"
}

Items

Items are individual services for a coverage that can be claimed for funding by the NDIS. Each member’s plan contains coverages that is made up of items that the member is eligible to claim against, including a price for each item.

Search Claimable Items

GET /plans/{planKey}/items?query={query}&page={page}

Use this resource to search for claimable items against a member’s plan.

Path Parameters

Field	Format	Required?	Description
planKey	UUID	Mandatory	The plan key for the member returned in the `lp:links` `_links:self` section of the Get a Member response.

Query Parameters

Field	Format	Required?	Description
query	string	Mandatory	The search term to find an item. Will match against item code, item name, item description or item price. For example, `items?query="gel"` to find all items with `gel` in the description.
page	integer	Mandatory	The page number of results to return. The first page is 0 and each page will show 50 results. The response will identify how many pages of results there are from the query - see example.

Example Search Claimable Items Request

{
    "_links": {
        "self": {
            "href": "https://api.sandbox.lanternpay.com/plans/7810d904-1bce-41a9-9090-4cbca40b65d4/items?page=0&amp;query=%22gel%22"
        },
        "lp:first": {
            "href": "https://api.sandbox.lanternpay.com/plans/7810d904-1bce-41a9-9090-4cbca40b65d4/items?page=0&amp;query=%22gel%22"
        },
        "lp:last": {
            "href": "https://api.sandbox.lanternpay.com/plans/7810d904-1bce-41a9-9090-4cbca40b65d4/items?page=1&amp;query=%22gel%22"
        },
        "lp:next": {
            "href": "https://api.sandbox.lanternpay.com/plans/7810d904-1bce-41a9-9090-4cbca40b65d4/items?page=1&amp;query=%22gel%22"
        },
        "curies": {
            "name": "lp",
            "href": "https://docs.lanternpay.com/reference#{rel}",
            "templated": true
        }
    },
    "resultsPerPage": 50,
    "pageNumber": 0,
    "pageCount": 1,
    "results": [
        {
            "key": "bc98f13e-0b19-4a5f-98c2-fc5e689cde5e",
            "code": "03_092406057_0103_1_1",
            "name": "Continence Package B - Intermittent Mild - Annual Amount",
            "description": "3 per day intermittent catheters with gel and lubricant - annual amount.",
            "price": null,
            "priceIncludesTax": true,
            "unitOfMeasure": "Hours",
            "type": "item",
            "statePricing": {
                "act": null,
                "nsw": null,
                "nt": null,
                "qld": null,
                "sa": null,
                "tas": null,
                "vic": null,
                "wa": null
            }
        },
        {
            "key": "8b2ce849-f6c4-4c4b-90e8-bc0ca15ad458",
            "code": "03_092406059_0103_1_1",
            "name": "Continence Package D - Intermittent Higher Needs - Annual Amount",
            "description": "6 per day intermittent catheters with gel and lubricant - annual amount.",
            "price": null,
            "priceIncludesTax": true,
            "unitOfMeasure": "Hours",
            "type": "item",
            "statePricing": {
                "act": null,
                "nsw": null,
                "nt": null,
                "qld": null,
                "sa": null,
                "tas": null,
                "vic": null,
                "wa": null
            }
        },
        {
            "key": "034e806b-6020-4fb5-a227-8aa539b97a07",
            "code": "03_092406058_0103_1_1",
            "name": "Continence Package C - Intermittent Moderate - Annual Amount",
            "description": "4 per day intermittent catheters with gel and lubricant - annual amount.",
            "price": null,
            "priceIncludesTax": true,
            "unitOfMeasure": "Hours",
            "type": "item",
            "statePricing": {
                "act": null,
                "nsw": null,
                "nt": null,
                "qld": null,
                "sa": null,
                "tas": null,
                "vic": null,
                "wa": null
            }
        }
    ]
}

Get a Member’s Most Used Items

GET /members/{memberKey}/itemusages

Use this resource to pull a list of the most frequently used items for a member. This can be a useful resource to speed up the process of plan managers creating invoices for their members by showing, or pre-populating, a list of frequently used items for that member.

Path Parameters

Field	Format	Required?	Description
memberKey	UUID	Mandatory	The memberKey provided after a member is created.

Example Get a Member’s Most Used Items Response

{
    "_links": {
        "self": {
            "href": "https://api.sandbox.lanternpay.com/members/35161601-6821-41fa-8fc6-64975f0d58e4/itemusages"
        },
        "curies": {
            "name": "lp",
            "href": "https://docs.lanternpay.com/reference#{rel}",
            "templated": true
        }
    },
    "_embedded": {
        "lp:items": [
            {
                "name": "Transitional Support",
                "description": "Transition to NDIS funding – payment of rent and utility accounts. Short term payment as per participant plan.",
                "popularity": 34,
                "code": "01_001_0101_1_1",
                "itemKey": "fc48c1e3-eab7-4989-88e4-2e12148f9113",
                "count": 5
            }
        ]
    }
}

Invoices

Service providers (for example, a Physiotherapist) issue invoices which can be submitted to LanternPay by plan managers for processing and then funding by the NDIS. As the NDIS only supports funding for individual claims (i.e. line items on an invoice) LanternPay manages the link between invoices for providers or plan managers and claims for the NDIS. Furthermore, LanternPay can route invoices to a plan manager for authorization which were submitted directly to LanternPay by a registered service provider.

See here for an explanation of the difference between registered biller invoices and a unregistered biller invoices (i.e. payee invoices)

See here for a full list of all invoice and claim statuses.

Create a Payee Invoice

POST /planmanagers/{planManagerKey}/members/{memberKey}/invoices

Use this resource to create payee invoices for plan managed members. This creates a draft of the invoice with LanternPay which is pre-processed to advise of any issues or errors with the invoice. A unique invoiceKey is issued when a draft invoice is created and this is used to submit the invoice (with no expiration time) - if no errors were found with the draft invoice, the lp:submit-invoice link can be used to submit the draft invoice for processing and payment.

Path Parameters

Field	Format	Required?	Description
planManagerKey	UUID	Mandatory	The unique identifier for the plan manager submitting the invoice.
memberKey	UUID	Mandatory	The memberKey provided after a member is created.

Body Parameters

Field	Format	Required?	Description
payee	object	Mandatory	The payee details for the biller being paid by this invoice. See Payee Object below.
invoiceDate	YYYY-MM-DD	Mandatory	The date of shown on the invoice.
invoiceNumber	string	Mandatory	The invoice number or reference shown on the invoice.
claims	array of objects	Mandatory	The container object for an array of claims on the invoice. See Claims Object Parameters below.

Payee Object Parameters

Some of these details (see below) will be used on the remittance advice issued to the biller.

Field	Format	Required?	Description
name	string	Mandatory	The payee’s full name or business name - used on the remittance advice.
abn	11 digits or a valid NDIS mnemonic	Optional	The payee’s ABN, this is submitted with the claim to the NDIA. This field is mandatory when the payee possesses a valid ABN. If the payee does not possess a valid ABN then a valid NDIA omission reason mnemonic should be included. If the ABN is omitted or the ABN does not conform to the defined ABN format, then a defult value of `REIMB` will be used.
email	string	Mandatory	The payee’s email - used on the remittance advice.
reference	string	Mandatory	The integration partner’s unique reference for the payee.
bankAccount	object	Mandatory	The payee’s bank account - used for settlement of funds. See Payee Bank Account Object Parameters below.

Payee Bank Account Object Parameters

These details will be used for settlement of funds to the biller.

Note: no validation is done by LanternPay on the bank account details for a payee (unregistered biller), so it is up to the plan manager to ensure that the details entered for the invoice are correct at the time the invoice is submitted.

Field	Format	Required?	Description
bsb	6 digits	Mandatory	The BSB of the payee’s bank account.
accountNumber	1 to 9 digits	Mandatory	The account number of the payee’s bank account.
accountHolder	string	Mandatory	The personal/business name of the bank account holder.

Payee ABN Values

The NDIS requires that a valid ABN be provided whenever one is present. If a valid ABN is not present, then an ABN omission reason will need to be supplied. If no omission reason is provided, then LanternPay will default the claim to provide the “Reimbursment” reason mnemonic, REIMB. The below table lists accepted values for this field:

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.

Claims Object Parameters

Field	Format	Required?	Description
lineItemId	string	Optional	Your unique identifier for the claim line item. These are returned in the GET Payment File response to aid financial reconciliation.
itemCode	string	Mandatory	The unique identifer for the item to be claimed.
unitPriceIncTax	currency	Mandatory	The unit price, including tax, of the item to be claimed to two decimal places. For example, $12.76 would be `"unitPriceIncTax":"12.76"`
startDate	YYYY-MM-DD	Mandatory	The date the claimable service started.
endDate	YYYY-MM-DD	Mandatory	The date the claimable service ended.
quantity	object - see description	Mandatory	The quantity units to be billed. For a time duration, you should convert this to a value of the unit price rounded to 2 decimal places. For example, for an item that is billed hourly, and the service time was 20 minutes, you should enter quanty as: `"quantity":{"units":"0.33"}`
gstCode	NDIS GST Codes	Optional	A valid NDIS Gst Code, if omitted the claim will be submitted with a value of `"P2"`.
claimType	NDIS Claim Type	Optional	The type of claim that that is being submitted, must be a valid NDIS Claim Type.
cancellationReason	Cancellation Claim Reason	Conditional	The cancellation claim reason code, this should only be provided when the NDIS Claim Type is `"CANC"`, a valid Cancellation Claim Reason must be provided when the claimType is `"CANC"`.

NDIS GST Codes

The NDIS GST Codes are reporting fields defined by the NDIS to communicate the tax status of the claim. The NDIS accepts three values in this field, these are defined by the NDIS as follows:

Value	Description
P1	Tax Claimable (10%)
P2	GST Free
P5	GST Out of Scope

NDIS Claim Types

The NDIS has defined a number of claim types that can be submitted to the NDIS. These mostly are used for reporting functions. It should be noted that a claim type of "CANC" is not used to cancel a previously submitted claim and is defined as a type of claim. For standard claims, this field should be left blank or omitted. The NDIS accepts the following claim types:

Value	Description
CANC	Cancellation. If cancellation is selected then a valid Cancellation Reason value must be provided.
REPW	NDIA Required Report.
TRAN	Provider Travel.
NF2F	Non-Face-to-Face Services.
THLT	Telehealth Supports.
IRSS	Irregular SIL Supports.

Cancellation Claim Reasons

Cancellation claims reasons are required for NDIS claims when a Cancellation claim is submitted. The NDIS accepts the following cancellation reason codes:

Value	Description
NSDH	No show due to health reason.
NSDF	No show due to family issues.
NSDT	No show due to unavailability of transport.
NSDO	Other

Example Create Payee Invoice Request

{
    "payee": {
        "name": "Test Payee 55",
        "abn": "51824753556",
        "email": "test.payee.55@lanternpay.com",
        "reference": "prov1092673",
        "bankAccount": {
            "bsb": "123453",
            "accountNumber": "541234",
            "accountHolder": "Test Payee 55"
        }
    },
    "invoiceDate": "2021-01-01",
    "invoiceNumber": "FF_ON_Test_3",
    "claims": [
        {
            "lineItemId": "321_001",
            "itemCode": "01_001_0101_1_1",
            "unitPriceIncTax": 3,
            "startDate": "2021-01-01",
            "endDate": "2021-01-01",
            "gstCode": "P1",
            "quantity": {
                "units": 1
            }
        },
        {
            "lineItemId": "321_002",
            "itemCode": "01_001_0101_1_1",
            "unitPriceIncTax": 3,
            "startDate": "2021-01-01",
            "endDate": "2021-01-01",
            "gstCode": "P2",
            "claimType": "IRSS",
            "quantity": {
                "units": 1
            }
        },
        {
            "lineItemId": "321_003",
            "itemCode": "01_001_0101_1_1",
            "unitPriceIncTax": 3,
            "startDate": "2021-01-01",
            "endDate": "2021-01-01",
            "gstCode": "P5",
            "claimType": "CANC",
            "cancellationReason": "NSDH",
            "quantity": {
                "units": 1
            }
        },
        {
            "lineItemId": "321_004",
            "itemCode": "01_001_0101_1_1",
            "unitPriceIncTax": 3,
            "startDate": "2021-01-01",
            "endDate": "2021-01-01",
            "quantity": {
                "units": 1
            }
        }
    ]
}

Example Create Payee Invoice Response

{
    "_links": {
        "self": {
            "href": "https://api.sandbox.lanternpay.com/invoices/a3566e07-8715-43ff-baad-a516661e8b8c"
        },
        "lp:submit-invoice": {
            "href": "https://api.sandbox.lanternpay.com/invoices/a3566e07-8715-43ff-baad-a516661e8b8c/submit"
        },
        "curies": {
            "name": "lp",
            "href": "https://docs.lanternpay.com/reference#{rel}",
            "templated": true
        }
    },
    "invoiceKey": "a3566e07-8715-43ff-baad-a516661e8b8c",
    "invoiceDate": "2021-01-01",
    "invoiceNumber": "FF_ON_Test_3",
    "totalClaimAmount": 12,
    "claims": [
        {
            "claimKey": "9e0831f3-83a6-47a8-9ff4-390959f26711",
            "itemCode": "01_001_0101_1_1",
            "itemName": "Transitional Support",
            "lineItemId": "321_001",
            "unitPriceIncTax": 3,
            "unitTax": 0,
            "quantity": {
                "units": 1,
                "duration": ""
            },
            "totalPrice": 3,
            "totalClaimAmount": 3,
            "funded": 0,
            "taxCode": "FRE",
            "state": {
                "value": 5,
                "displayName": "Authorized"
            },
            "fundingSources": [
                {
                    "name": "NDIS",
                    "insufficientContributionReasons": [],
                    "contribution": 3,
                    "requiresAuthorization": false
                }
            ],
            "serviceStartTime": "2021-01-01",
            "serviceEndTime": "2021-01-01",
            "gstCode": "P1",
            "validationErrors": []
        },
        {
            "claimKey": "cb9c211a-7d5c-47bc-b15f-f44cb6b497a8",
            "itemCode": "01_001_0101_1_1",
            "itemName": "Transitional Support",
            "lineItemId": "321_002",
            "unitPriceIncTax": 3,
            "unitTax": 0,
            "quantity": {
                "units": 1,
                "duration": ""
            },
            "totalPrice": 3,
            "totalClaimAmount": 3,
            "funded": 0,
            "taxCode": "FRE",
            "state": {
                "value": 5,
                "displayName": "Authorized"
            },
            "fundingSources": [
                {
                    "name": "NDIS",
                    "insufficientContributionReasons": [],
                    "contribution": 3,
                    "requiresAuthorization": false
                }
            ],
            "serviceStartTime": "2021-01-01",
            "serviceEndTime": "2021-01-01",
            "gstCode": "P2",
            "claimType": "IRSS",
            "validationErrors": []
        },
        {
            "claimKey": "ee4050b1-febc-48e2-93f8-215f10326a6d",
            "itemCode": "01_001_0101_1_1",
            "itemName": "Transitional Support",
            "lineItemId": "321_003",
            "unitPriceIncTax": 3,
            "unitTax": 0,
            "quantity": {
                "units": 1,
                "duration": ""
            },
            "totalPrice": 3,
            "totalClaimAmount": 3,
            "funded": 0,
            "taxCode": "FRE",
            "state": {
                "value": 5,
                "displayName": "Authorized"
            },
            "fundingSources": [
                {
                    "name": "NDIS",
                    "insufficientContributionReasons": [],
                    "contribution": 3,
                    "requiresAuthorization": false
                }
            ],
            "serviceStartTime": "2021-01-01",
            "serviceEndTime": "2021-01-01",
            "gstCode": "P5",
            "claimType": "CANC",
            "cancellationReason": "NSDH",
            "validationErrors": []
        },
        {
            "claimKey": "38b1a052-8f7f-430d-adbd-8e85c862b8ce",
            "itemCode": "01_001_0101_1_1",
            "itemName": "Transitional Support",
            "lineItemId": "321_004",
            "unitPriceIncTax": 3,
            "unitTax": 0,
            "quantity": {
                "units": 1,
                "duration": ""
            },
            "totalPrice": 3,
            "totalClaimAmount": 3,
            "funded": 0,
            "taxCode": "FRE",
            "state": {
                "value": 5,
                "displayName": "Authorized"
            },
            "fundingSources": [
                {
                    "name": "NDIS",
                    "insufficientContributionReasons": [],
                    "contribution": 3,
                    "requiresAuthorization": false
                }
            ],
            "serviceStartTime": "2021-01-01",
            "serviceEndTime": "2021-01-01",
            "validationErrors": []
        }
    ],
    "payee": {
        "name": "Test Payee 55",
        "abn": "51824753556",
        "email": "test.payee.55@lanternpay.com",
        "reference": "prov1092673",
        "bankAccount": {
            "bsb": "123453",
            "accountNumber": "541234",
            "accountHolder": "Test Payee 55"
        }
    },
    "funded": 0,
    "state": {
        "value": 1,
        "displayName": "Draft"
    }
}

Submit a Payee Invoice

POST /invoices/{invoiceKey}/submit

This resources allows draft invoices, via their invoiceKey to be submitted for processing by the NDIS. Any valid invoice submitted via the API will be sent to the NDIS for funding.

Path Parameters

Field	Format	Required?	Description
invoiceKey	UUID	Mandatory	The invoiceKey provided after an invoice is created.

Example Submit Payee Invoice Response

{
    "_links": {
        "self": {
            "href": "https://api.sandbox.lanternpay.com/invoices/a3566e07-8715-43ff-baad-a516661e8b8c/submit"
        },
        "curies": {
            "name": "lp",
            "href": "https://docs.lanternpay.com/reference#{rel}",
            "templated": true
        }
    },
    "biller": null,
    "invoiceKey": "a3566e07-8715-43ff-baad-a516661e8b8c",
    "invoiceDate": "2021-01-01",
    "invoiceNumber": "FF_ON_Test_3",
    "totalClaimAmount": 12,
    "claims": [
        {
            "claimKey": "9e0831f3-83a6-47a8-9ff4-390959f26711",
            "itemCode": "01_001_0101_1_1",
            "itemName": "Transitional Support",
            "lineItemId": "321_001",
            "unitPriceIncTax": 3,
            "unitTax": 0,
            "quantity": {
                "units": 1,
                "duration": "0:00"
            },
            "totalPrice": 3,
            "totalClaimAmount": 3,
            "funded": 0,
            "taxCode": "FRE",
            "state": {
                "value": 5,
                "displayName": "Authorized"
            },
            "fundingSources": [
                {
                    "name": "NDIS",
                    "insufficientContributionReasons": [],
                    "contribution": 3,
                    "requiresAuthorization": false
                }
            ],
            "serviceStartTime": "2021-01-01",
            "serviceEndTime": "2021-01-01",
            "gstCode": "P1",
            "claimType": "",
            "cancellationReason": "",
            "validationErrors": []
        },
        {
            "claimKey": "cb9c211a-7d5c-47bc-b15f-f44cb6b497a8",
            "itemCode": "01_001_0101_1_1",
            "itemName": "Transitional Support",
            "lineItemId": "321_002",
            "unitPriceIncTax": 3,
            "unitTax": 0,
            "quantity": {
                "units": 1,
                "duration": "0:00"
            },
            "totalPrice": 3,
            "totalClaimAmount": 3,
            "funded": 0,
            "taxCode": "FRE",
            "state": {
                "value": 5,
                "displayName": "Authorized"
            },
            "fundingSources": [
                {
                    "name": "NDIS",
                    "insufficientContributionReasons": [],
                    "contribution": 3,
                    "requiresAuthorization": false
                }
            ],
            "serviceStartTime": "2021-01-01",
            "serviceEndTime": "2021-01-01",
            "gstCode": "P2",
            "claimType": "IRSS",
            "cancellationReason": "",
            "validationErrors": []
        },
        {
            "claimKey": "ee4050b1-febc-48e2-93f8-215f10326a6d",
            "itemCode": "01_001_0101_1_1",
            "itemName": "Transitional Support",
            "lineItemId": "321_003",
            "unitPriceIncTax": 3,
            "unitTax": 0,
            "quantity": {
                "units": 1,
                "duration": "0:00"
            },
            "totalPrice": 3,
            "totalClaimAmount": 3,
            "funded": 0,
            "taxCode": "FRE",
            "state": {
                "value": 5,
                "displayName": "Authorized"
            },
            "fundingSources": [
                {
                    "name": "NDIS",
                    "insufficientContributionReasons": [],
                    "contribution": 3,
                    "requiresAuthorization": false
                }
            ],
            "serviceStartTime": "2021-01-01",
            "serviceEndTime": "2021-01-01",
            "gstCode": "P5",
            "claimType": "CANC",
            "cancellationReason": "NSDH",
            "validationErrors": []
        },
        {
            "claimKey": "38b1a052-8f7f-430d-adbd-8e85c862b8ce",
            "itemCode": "01_001_0101_1_1",
            "itemName": "Transitional Support",
            "lineItemId": "321_004",
            "unitPriceIncTax": 3,
            "unitTax": 0,
            "quantity": {
                "units": 1,
                "duration": "0:00"
            },
            "totalPrice": 3,
            "totalClaimAmount": 3,
            "funded": 0,
            "taxCode": "FRE",
            "state": {
                "value": 5,
                "displayName": "Authorized"
            },
            "fundingSources": [
                {
                    "name": "NDIS",
                    "insufficientContributionReasons": [],
                    "contribution": 3,
                    "requiresAuthorization": false
                }
            ],
            "serviceStartTime": "2021-01-01",
            "serviceEndTime": "2021-01-01",
            "gstCode": "P2",
            "claimType": "",
            "cancellationReason": "",
            "validationErrors": []
        }
    ],
    "submittedAtUtc": "2021-04-22T02:47:05.459Z",
    "payee": {
        "reference": "prov1092673",
        "name": "Test Payee 55",
        "email": "test.payee.55@lanternpay.com",
        "abn": "51824753556",
        "bankAccount": {
            "bsb": "123453",
            "accountNumber": "541234",
            "accountHolder": "Test Payee 55"
        }
    },
    "funded": 0,
    "programCode": "NDIS",
    "state": {
        "value": 3,
        "displayName": "Processed"
    }
}

Get an Invoice

GET /invoices/{invoiceKey}

Use this resource to retrieve the full details of a specific invoice, via the invoiceKey.

This API can be used to retrieve payee invoices (which are submitted by the plan manager on behalf of an unregistered biller) and registered biller invoices (which are submitted directly to LanternPay by the registered biller).

If the invoice being retrived is a payee invoice, the payee node will be populated and the biller node will be null.
If the invoice being retrieved was submitted by a registered biller the biller node will be populated and the payee node will be null.

See here for a full list of all invoice and claim statuses.

Additionally, we have a number of invoice webhooks which trigger on certain events to provide updates of the processing and/or payment status of the claim(s) on the invoice. See Invoice Webhooks section for more information

When an invoice has been submitted to the NDIS, the ndisReference field will be populated, per claim, showing the unique claim reference visible in the NDIS portal.

Path Parameters

Field	Format	Required?	Description
invoiceKey	UUID	Mandatory	The invoiceKey provided after an invoice is created.

Example Get an Invoice Response

{
    "_links": {
        "self": {
            "href": "https://api.sandbox.lanternpay.com/invoices/a3566e07-8715-43ff-baad-a516661e8b8c"
        },
        "curies": {
            "name": "lp",
            "href": "https://docs.lanternpay.com/reference#{rel}",
            "templated": true
        }
    },
    "invoiceKey": "a3566e07-8715-43ff-baad-a516661e8b8c",
    "invoiceDate": "2021-01-01",
    "invoiceNumber": "FF_ON_Test_3",
    "submittedAtUtc": "2021-04-22T00:00:00",
    "state": {
        "value": 3,
        "displayName": "Processed"
    },
    "biller": null,
    "totalClaimAmount": 12,
    "funded": 12,
    "claims": [
        {
            "claimKey": "cb9c211a-7d5c-47bc-b15f-f44cb6b497a8",
            "itemCode": "01_001_0101_1_1",
            "itemName": "transitional support",
            "unitPriceIncTax": 3,
            "unitTax": 0,
            "quantity": {
                "units": 1,
                "duration": "0:00"
            },
            "totalPrice": 3,
            "totalClaimAmount": 3,
            "funded": 3,
            "taxCode": "FRE",
            "state": {
                "value": 13,
                "displayName": "AuthorizedByProgram"
            },
            "lineItemId": "321_002",
            "fundingSources": [
                {
                    "insufficientContributionReasons": [],
                    "contribution": 3,
                    "requiresAuthorization": false,
                    "name": "NDIS",
                    "contractNumber": null,
                    "preauthorizationNumber": null
                }
            ],
            "serviceStartTime": "2021-01-01",
            "serviceEndTime": "2021-01-01",
            "gstCode": "P2",
            "claimType": "IRSS",
            "cancellationReason": "",
            "validationErrors": [],
            "ndisReference": "0dc75918-c8fb-4142-b763-b28886e2a89d"
        },
        {
            "claimKey": "38b1a052-8f7f-430d-adbd-8e85c862b8ce",
            "itemCode": "01_001_0101_1_1",
            "itemName": "transitional support",
            "unitPriceIncTax": 3,
            "unitTax": 0,
            "quantity": {
                "units": 1,
                "duration": "0:00"
            },
            "totalPrice": 3,
            "totalClaimAmount": 3,
            "funded": 3,
            "taxCode": "FRE",
            "state": {
                "value": 13,
                "displayName": "AuthorizedByProgram"
            },
            "lineItemId": "321_004",
            "fundingSources": [
                {
                    "insufficientContributionReasons": [],
                    "contribution": 3,
                    "requiresAuthorization": false,
                    "name": "NDIS",
                    "contractNumber": null,
                    "preauthorizationNumber": null
                }
            ],
            "serviceStartTime": "2021-01-01",
            "serviceEndTime": "2021-01-01",
            "gstCode": "P2",
            "claimType": "",
            "cancellationReason": "",
            "validationErrors": [],
            "ndisReference": "c757fb3d-9347-457d-aa30-f2e0af55fcf2"
        },
        {
            "claimKey": "ee4050b1-febc-48e2-93f8-215f10326a6d",
            "itemCode": "01_001_0101_1_1",
            "itemName": "transitional support",
            "unitPriceIncTax": 3,
            "unitTax": 0,
            "quantity": {
                "units": 1,
                "duration": "0:00"
            },
            "totalPrice": 3,
            "totalClaimAmount": 3,
            "funded": 3,
            "taxCode": "FRE",
            "state": {
                "value": 13,
                "displayName": "AuthorizedByProgram"
            },
            "lineItemId": "321_003",
            "fundingSources": [
                {
                    "insufficientContributionReasons": [],
                    "contribution": 3,
                    "requiresAuthorization": false,
                    "name": "NDIS",
                    "contractNumber": null,
                    "preauthorizationNumber": null
                }
            ],
            "serviceStartTime": "2021-01-01",
            "serviceEndTime": "2021-01-01",
            "gstCode": "P5",
            "claimType": "CANC",
            "cancellationReason": "NSDH",
            "validationErrors": [],
            "ndisReference": "a16d1842-de07-4584-bd1e-224d4becbfa7"
        },
        {
            "claimKey": "9e0831f3-83a6-47a8-9ff4-390959f26711",
            "itemCode": "01_001_0101_1_1",
            "itemName": "transitional support",
            "unitPriceIncTax": 3,
            "unitTax": 0,
            "quantity": {
                "units": 1,
                "duration": "0:00"
            },
            "totalPrice": 3,
            "totalClaimAmount": 3,
            "funded": 3,
            "taxCode": "FRE",
            "state": {
                "value": 13,
                "displayName": "AuthorizedByProgram"
            },
            "lineItemId": "321_001",
            "fundingSources": [
                {
                    "insufficientContributionReasons": [],
                    "contribution": 3,
                    "requiresAuthorization": false,
                    "name": "NDIS",
                    "contractNumber": null,
                    "preauthorizationNumber": null
                }
            ],
            "serviceStartTime": "2021-01-01",
            "serviceEndTime": "2021-01-01",
            "gstCode": "P1",
            "claimType": "",
            "cancellationReason": "",
            "validationErrors": [],
            "ndisReference": "1ead51d0-24ac-4138-ad75-653eae54738d"
        }
    ],
    "programCode": "ndis",
    "payee": {
        "reference": "prov1092673",
        "name": "Test Payee 55",
        "email": "test.payee.55@lanternpay.com",
        "abn": "51824753556",
        "bankAccount": {
            "bsb": "123453",
            "accountNumber": "541234",
            "accountHolder": "Test Payee 55"
        }
    }
}

Authorize an Invoice

POST /invoices/{invoiceKey}/authorize

This resources allows a plan manager to authorize or reject individual claims on an invoice submitted by a registered service provider directly to LanternPay. If a service provider submits an invoice for a member with claims that are not covered under a contract (see Contracts) then it must be authorized by the member’s plan manager before LanternPay will process the claim to the NDIS.

Note: claims on an invoice can be authorized individually, and hence, can be processed and sent to the NDIS for funding individually which can result in an invoice being funded for all claims over multiple funding cycles by the NDIS.

Path Parameters

Field	Format	Required?	Description
invoiceKey	UUID	Mandatory	The invoiceKey provided after an invoice is created.

Body Parameters

Field	Format	Required?	Description
claims	array of objects	Mandatory	The container object for an array of claims to reject or authorize. All claims on a given invoice must have an authorization action performed on them before the invoice will be processed for payment. See table below.

Claims Object Parameters

Field	Format	Required?	Description
claimKey	UUID	Mandatory	The UUID for the individual claim shown in the Get Invoice API response.
action	string	Mandatory	The authorization action for the individual claim. Can be either `authorize` or `reject`.

Example Authorize an Invoice Request

{
    "claims": [
        {
            "claimKey": "51837a68-1e76-083d-155a-b3185126cebf",
            "action": "authorize"
        },
        {
            "claimKey": "ef0e8a85-5dbe-0a7b-39fd-249a36f007d0",
            "action": "authorize"
        },
        {
            "claimKey": "723347b6-3806-0792-0f9f-56a3d2fb8997",
            "action": "reject"
        }
    ]
}

Example Authorize an Invoice Response

{
    "_links": {
        "self": {
            "href": "https://api.sandbox.lanternpay.com/invoices/ba47e124-7810-0c51-023b-c2f6af7ceca1/authorize"
        },
        "lp:get-invoice": {
            "href": "https://api.sandbox.lanternpay.com/invoices/ba47e124-7810-0c51-023b-c2f6af7ceca1"
        },
        "curies": {
            "name": "lp",
            "href": "https://docs.lanternpay.com/reference#{rel}",
            "templated": true
        }
    }
}

Invoice Webhooks

WEBHOOK {invoiceWebhookUri}

We have a number of invoice webhook types which will fire on certain events that indicate that some data has changed on an invoice. The different invoice webhook types are intended to give integration partners more context when doing a lookup on an invoice to determine what data might have changed and what actions may follow those changes.

The strucutre of the invoice payload, see examples to the right, is the same for each invoice webhook - the only difference is the value of the type field, described below, which indicates the event that triggered the webhook.

Path Parameters

Field	Format	Required	Description
invoiceWebhookUri	URI	Mandatory	The URI, per plan manager, you provided to LanternPay during onboarding.

Body Parameters

Field	Format	Required	Description
id	UUID	Mandatory	A unqiue ID for the event.
created	Unix Epoch Time	Mandatory	The date and time in Unix Epoch Time the webhook was triggered.
data	object	Mandatory	The container object for the webhook data. See table below.
type	string	Mandatory	The event that triggered the webhook. Valid webhook types are described below.

Data Object Parameters

Field	Format	Required	Description
membershipNumber	string	Mandatory	The NDIS membership number for the participant the invoice was raised against.
programCode	string	Mandatory	The LanternPay program code for NDIS which is: `ndis`
invoiceUri	URI	Mandatory	The link to the invoice resource. Use the Get an Invoice API operation to view the invoice and its claims.

Webhook Types

Type	Event Description
claiming.invoice.processed	An invoice is submitted by a plan manager via the Plan Manager API and LanternPay has completed processing of the invoice.
claiming.invoice.received	An invoice is submitted by a provider directly to LanternPay and LanternPay has completed processing of the invoice.
claiming.invoice.fundingDecision	The NDIS has responded to at least one claim submission on an invoice and LanternPay has processed the NDIS response for the invoice.
claiming.invoice.cancelled	LanternPay has received a request to cancel one or more claims on an invoice and has completed the cancellation.
claiming.invoice.adjusted	This is reserved for future use.

Example Invoice Processed Webhook

{
    "id": "c3042c70-29ce-4c86-8e1b-310e48t8932a",
    "created": 1559604212,
    "data": {
        "membershipNumber": "123456789",
        "programCode": "ndis",
        "invoiceUri": "https://api.sandbox.lanternpay.com/invoices/44333588-2da3-487c-952e-54dd373zgd1f"
    },
    "type": "claiming.invoice.processed"
}

Example Invoice Received Webhook

{
    "id": "c3042c70-29ce-4c86-8e1b-310e48t8932a",
    "created": 1559604212,
    "data": {
        "membershipNumber": "123456789",
        "programCode": "ndis",
        "invoiceUri": "https://api.sandbox.lanternpay.com/invoices/44333588-2da3-487c-952e-54dd373zgd1f"
    },
    "type": "claiming.invoice.received"
}

Example Invoice Funding Decision Webhook

{
    "id": "c3042c70-29ce-4c86-8e1b-310e48t8932a",
    "created": 1559604212,
    "data": {
        "membershipNumber": "123456789",
        "programCode": "ndis",
        "invoiceUri": "https://api.sandbox.lanternpay.com/invoices/44333588-2da3-487c-952e-54dd373zgd1f"
    },
    "type": "claiming.invoice.fundingDecision"
}

Example Invoice Cancelled Webhook

{
    "id": "c3042c70-29ce-4c86-8e1b-310e48t8932a",
    "created": 1559604212,
    "data": {
        "membershipNumber": "123456789",
        "programCode": "ndis",
        "invoiceUri": "https://api.sandbox.lanternpay.com/invoices/44333588-2da3-487c-952e-54dd373zgd1f"
    },
    "type": "claiming.invoice.cancelled"
}

Contracts

A contract is an agreement between a member and a LanternPay registered service provider that a portion of funds from the member’s plan is reserved for that service provider. This could be a general amount which can be used for a number of different coverages or a specific amount per coverage.

This means that when a service provider submits an invoice directly to LanternPay and one or more of the claims on the invoice are covered under a contract for the member then those claims will be automatically approved for processing to the NDIS.

If you are interested in more information regarding contracts, please contact integrations@lanternpay.com

Payments

Payments are funds disbursed by LanternPay to a biller for a service provided to a member. For NDIS, LanternPay requests funds from the NDIS on behalf of a plan manager and then once those funds are paid by the NDIS, LanternPay will disburse those funds to the billers as a rolled up (NET) payment.

LanternPay will also issue a remittance advice to the biller advising of the payment and a breakdown of all the invoices/claims for a particiular plan manager that made up the payment for that day.

onPaymentScheduled Webhook

WEBHOOK {onPaymentScheduledUri}

This webhook will trigger once per day per plan manager when a payment file is generated and sent to the bank for processing. The webhook body contains a paymentUri which can be used to retrieve a list of payments - see Get a List of Payments below.

Path Parameters

Field	Format	Required?	Description
onPaymentScheduledUri	URI	Mandatory	The URI, per plan manager, you provided to LanternPay during onboarding.

Body Parameters

Field	Format	Required?	Description
id	UUID	Mandatory	A unqiue ID for the event.
created	Unix Epoch Time	Mandatory	The date and time in Unix Epoch Time the webhook was triggered.
data	object	Mandatory	The container object for the webhook data. See table below.
type	string	Mandatory	The event type that triggered the webhook.

Data Object Parameters

Field	Format	Required?	Description
paymentUri	URI	Mandatory	The link to be used for the Get a List of Payments API request shown below. You may wish to store the `directEntryFileUKey` value in the URI to query the file at a later date.

Example onPaymentScheduled Webhook

{
    "id": "ff8ab070-0821-4e73-bbe9-fa4df9f58e84",
    "created": 1549415502,
    "data": {
        "paymentUri": "https://api.sandbox.lanternpay.com/payments?directEntryFileUKey=60c27986-0208-48ab-a3b0-0edcbac0b1bf"
    },
    "type": "settlements.payments.scheduled"
}

Get a List of Payments

GET /payments?directEntryFileUKey={directEntryFileUKey}

This resource will return a list of all payments that makes up a specific payment file. It contains a breakdown of all invoices and claims that the payment relates to, including full and part funded claims. This can be used to aid financial reconciliation for the plan manager for funds going in and out of their bank account.

Query Parameters

Field	Format	Required?	Description
directEntryFileUKey	UUID	Mandatory	The UUID provided in the `onPaymentScheduled` webhook.

Example Get a List of Payments Response

{
    "_links": {
        "self": {
            "href": "https://api.sandbox.lanternpay.com/payments?directEntryFileUKey=60c27986-0208-48ab-a3b0-0edcbac0b1bf"
        },
        "curies": {
            "name": "lp",
            "href": "https://docs.lanternpay.com/reference#{rel}",
            "templated": true
        }
    },
    "amount": 100,
    "date": "2019-02-06",
    "payments": [
        {
            "billerKey": "48cf5266-3ea3-040e-3b3a-f2d355c28a87",
            "amount": 100,
            "requestedDate": "2019-02-06",
            "paymentReference": "ndis20190206BZELNK",
            "contributions": [
                {
                    "invoiceNumber": "903512621",
                    "claimKey": "15149be3-cd41-46f7-a69b-d781bfa96507",
                    "amount": 50,
                    "memberKey": "35161601-6821-41fa-8fc6-64975f0d58e4",
                    "lineItemId": "06a3e612-e9c0-40ad-99d0-a9b40ac816db",
                    "ndisReference": "ce0ccf08-b879-474b-9d12-c72cb0291570"
                },
                {
                    "invoiceNumber": "903512622",
                    "claimKey": "d0683a31-fcee-4ee7-8c25-ea77b366b235",
                    "amount": 50,
                    "memberKey": "16ae911b-ef96-43b6-a693-389585e180c7",
                    "lineItemId": "10d55f41-2ad9-4a78-b4c8-53e0b8660a41",
                    "ndisReference": "b5169058-c858-4044-b28d-ef615de8cb96"
                }
            ]
        }
    ]
}