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.

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 External Link 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.883,
    "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/430b0abf-18ac-0205-3ad5-4bb4dc9659d5/members/238845545?programCode=ndis"
        },
        "lp:add-biller": {
            "href": "https://api.sandbox.lanternpay.com/members/35161601-6821-41fa-8fc6-64975f0d58e4/billers"
        },
        "lp:create-invoice": {
            "href": "https://api.sandbox.lanternpay.com/members/35161601-6821-41fa-8fc6-64975f0d58e4/invoices"
        },
        "lp:validate-contract": {
            "href": "https://api.sandbox.lanternpay.com/members/35161601-6821-41fa-8fc6-64975f0d58e4/contracts/validate"
        },
        "lp:list-contracts": {
            "href": "https://api.sandbox.lanternpay.com/members/35161601-6821-41fa-8fc6-64975f0d58e4/contracts"
        },
        "lp:list-billers": {
            "href": "https://api.sandbox.lanternpay.com/members/35161601-6821-41fa-8fc6-64975f0d58e4/billers"
        },
        "lp:most-used-items": {
            "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:plans": [
            {
                "_links": {
                    "self": {
                        "href": "https://api.sandbox.lanternpay.com/plans/7810d904-1bce-41a9-9090-4cbca40b65d4"
                    },
                    "lp:transaction-history": {
                        "href": "https://api.sandbox.lanternpay.com/plans/7810d904-1bce-41a9-9090-4cbca40b65d4/transactions{?fromDate,toDate}",
                        "templated": true
                    },
                    "lp:search-items": {
                        "href": "https://api.sandbox.lanternpay.com/plans/7810d904-1bce-41a9-9090-4cbca40b65d4/items{?query,page}",
                        "templated": true
                    },
                    "lp:invoice-history": {
                        "href": "https://api.sandbox.lanternpay.com/plans/7810d904-1bce-41a9-9090-4cbca40b65d4/invoices{?fromDate,toDate}",
                        "templated": true
                    }
                },
                "endDate": "2020-01-01",
                "startDate": "2019-01-01",
                "isActive": true,
                "programCode": "ndis",
                "totalBudget": {
                    "total": 14000,
                    "spent": 250,
                    "unspent": 13750,
                    "assigned": {
                        "total": 0,
                        "spent": 0,
                        "unspent": 0
                    },
                    "unassigned": 13750
                }
            }
        ]
    },
    "programs": [
        {
            "code": "ndis",
            "shortName": "NDIS",
            "longName": "National Disability Insurance Scheme"
        }
    ],
    "memberKey": "35161601-6821-41fa-8fc6-64975f0d58e4",
    "name": {
        "first": "Sam",
        "last": "Smith"
    },
    "membershipNumber": "238845545",
    "dateOfBirth": "1950-10-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 External Link 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/7810d904-1bce-41a9-9090-4cbca40b65d4"
        },
        "curies": {
            "name": "lp",
            "href": "https://docs.lanternpay.com/reference#{rel}",
            "templated": true
        }
    },
    "membershipNumber": "238845545",
    "programName": "NDIS",
    "coverages": [
        {
            "category": {
                "name": "Assistance with Daily Life (CORE)",
                "code": "0001"
            },
            "startDate": "2019-01-01",
            "endDate": "2020-01-01",
            "initialBudget": 10000,
            "budget": {
                "total": 10000,
                "spent": 650,
                "unspent": 9350,
                "assigned": {
                    "total": 0,
                    "spent": 0,
                    "unspent": 0
                },
                "unassigned": 9350
            },
            "programCoverageNumber": null
        },
        {
            "category": {
                "name": "Consumables (CORE)",
                "code": "0003"
            },
            "startDate": "2019-01-01",
            "endDate": "2020-01-01",
            "initialBudget": 4000,
            "budget": {
                "total": 4000,
                "spent": 0,
                "unspent": 4000,
                "assigned": {
                    "total": 0,
                    "spent": 0,
                    "unspent": 0
                },
                "unassigned": 4000
            },
            "programCoverageNumber": null
        }
    ],
    "totalFlexBudget": {
        "total": 0,
        "spent": 0,
        "unspent": 0,
        "assigned": {
            "total": 0,
            "spent": 0,
            "unspent": 0
        },
        "unassigned": 0
    },
    "totalBudget": {
        "total": 14000,
        "spent": 650,
        "unspent": 13350,
        "assigned": {
            "total": 0,
            "spent": 0,
            "unspent": 0
        },
        "unassigned": 13350
    },
    "totalStatedBudget": {
        "total": 14000,
        "spent": 650,
        "unspent": 13350,
        "assigned": {
            "total": 0,
            "spent": 0,
            "unspent": 0
        },
        "unassigned": 13350
    }
}

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&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 External Link 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&query=%22gel%22"
        },
        "lp:first": {
            "href": "https://api.sandbox.lanternpay.com/plans/7810d904-1bce-41a9-9090-4cbca40b65d4/items?page=0&query=%22gel%22"
        },
        "lp:last": {
            "href": "https://api.sandbox.lanternpay.com/plans/7810d904-1bce-41a9-9090-4cbca40b65d4/items?page=1&query=%22gel%22"
        },
        "lp:next": {
            "href": "https://api.sandbox.lanternpay.com/plans/7810d904-1bce-41a9-9090-4cbca40b65d4/items?page=1&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 9 or 11 digits Optional The payee’s ABN - used on the remittance advice.
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 6 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.

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

Example Create Payee Invoice Request

{
	"payee": {
        "name": "test-payee-001",
        "abn": "12345678911",
        "email": "test-payee-001@lanternpayabc.com",
        "reference": "test-payee-001",
        "bankAccount": {
            "bsb": "123456",
            "accountNumber": "231234",
            "accountHolder": "test-payee-001"
        }
    },
    "invoiceDate":"2020-03-04",
	"invoiceNumber":"PM-API-384505964",
	"claims":[
		{
			"lineItemId":"PM-API-384505964-1",
			"itemCode":"01_046_0115_1_1",
			"unitPriceIncTax":"50.00",
	        "startDate":"2020-03-04",
	        "endDate":"2020-03-04",
	        "quantity":{
	        	"units":"1"
	        }
		},
		{
			"lineItemId":"PM-API-384505964-2",
			"itemCode":"03_092406061_0103_1_1",
			"unitPriceIncTax":"100.00",
	        "startDate":"2020-03-04",
	        "endDate":"2020-03-04",
	        "quantity":{
	        	"units":"1"
	        }
		}
	]
}

Example Create Payee Invoice Response

{
    "_links": {
        "self": {
            "href": "https://api.sandbox.lanternpay.com/invoices/549be2f0-767d-4239-ac2a-a5c248414cda"
        },
        "lp:submit-invoice": {
            "href": "https://api.sandbox.lanternpay.com/invoices/549be2f0-767d-4239-ac2a-a5c248414cda/submit"
        },
        "curies": {
            "name": "lp",
            "href": "https://docs.lanternpay.com/reference#{rel}",
            "templated": true
        }
    },
    "invoiceKey": "549be2f0-767d-4239-ac2a-a5c248414cda",
    "invoiceDate": "2020-03-04",
    "invoiceNumber": "PM-API-384505964",
    "totalClaimAmount": 150,
    "claims": [
        {
            "claimKey": "ebbfe9f6-6299-4950-8aa1-00cf805d800b",
            "itemCode": "01_046_0115_1_1",
            "itemName": "Assistance In Individual Living Arrangement For Person With Complex Needs",
            "lineItemId": "PM-API-384505964-1",
            "unitPriceIncTax": "50.00",
            "unitTax": 0,
            "quantity": {
                "units": "1",
                "duration": ""
            },
            "totalPrice": 50,
            "totalClaimAmount": 50,
            "funded": 0,
            "taxCode": "FRE",
            "state": {
                "value": 5,
                "displayName": "Authorized"
            },
            "fundingSources": [
                {
                    "name": "NDIS",
                    "insufficientContributionReasons": [],
                    "contribution": 50,
                    "requiresAuthorization": false
                }
            ],
            "serviceStartTime": "2020-03-04",
            "serviceEndTime": "2020-03-04",
            "validationErrors": []
        },
        {
            "claimKey": "107f0300-a0ad-46fd-a364-8930893d3477",
            "itemCode": "03_092406061_0103_1_1",
            "itemName": "Adult Intermittent Catheters Standard 3/Day - Annual Amount",
            "lineItemId": "PM-API-384505964-2",
            "unitPriceIncTax": "100.00",
            "unitTax": 0,
            "quantity": {
                "units": "1",
                "duration": ""
            },
            "totalPrice": 100,
            "totalClaimAmount": 100,
            "funded": 0,
            "taxCode": "FRE",
            "state": {
                "value": 5,
                "displayName": "Authorized"
            },
            "fundingSources": [
                {
                    "name": "NDIS",
                    "insufficientContributionReasons": [],
                    "contribution": 100,
                    "requiresAuthorization": false
                }
            ],
            "serviceStartTime": "2020-03-04",
            "serviceEndTime": "2020-03-04",
            "validationErrors": []
        }
    ],
    "payee": {
        "name": "test-payee-001",
        "abn": "12345678911",
        "email": "test-payee-001@lanternpayabc.com",
        "reference": "test-payee-001",
        "bankAccount": {
            "bsb": "123456",
            "accountNumber": "231234",
            "accountHolder": "test-payee-001"
        }
    },
    "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/549be2f0-767d-4239-ac2a-a5c248414cda/submit"
        },
        "curies": {
            "name": "lp",
            "href": "https://docs.lanternpay.com/reference#{rel}",
            "templated": true
        }
    },
    "biller": null,
    "invoiceKey": "549be2f0-767d-4239-ac2a-a5c248414cda",
    "invoiceDate": "2020-03-04",
    "invoiceNumber": "PM-API-384505964",
    "totalClaimAmount": 150,
    "claims": [
        {
            "claimKey": "ebbfe9f6-6299-4950-8aa1-00cf805d800b",
            "itemCode": "01_046_0115_1_1",
            "itemName": "Assistance In Individual Living Arrangement For Person With Complex Needs",
            "lineItemId": "PM-API-384505964-1",
            "unitPriceIncTax": 50,
            "unitTax": 0,
            "quantity": {
                "units": 1,
                "duration": "0:00"
            },
            "totalPrice": 50,
            "totalClaimAmount": 50,
            "funded": 0,
            "taxCode": "FRE",
            "state": {
                "value": 5,
                "displayName": "Authorized"
            },
            "fundingSources": [
                {
                    "name": "NDIS",
                    "insufficientContributionReasons": [],
                    "contribution": 50,
                    "requiresAuthorization": false
                }
            ],
            "serviceStartTime": "2020-03-04",
            "serviceEndTime": "2020-03-04",
            "validationErrors": []
        },
        {
            "claimKey": "107f0300-a0ad-46fd-a364-8930893d3477",
            "itemCode": "03_092406061_0103_1_1",
            "itemName": "Adult Intermittent Catheters Standard 3/Day - Annual Amount",
            "lineItemId": "PM-API-384505964-2",
            "unitPriceIncTax": 100,
            "unitTax": 0,
            "quantity": {
                "units": 1,
                "duration": "0:00"
            },
            "totalPrice": 100,
            "totalClaimAmount": 100,
            "funded": 0,
            "taxCode": "FRE",
            "state": {
                "value": 5,
                "displayName": "Authorized"
            },
            "fundingSources": [
                {
                    "name": "NDIS",
                    "insufficientContributionReasons": [],
                    "contribution": 100,
                    "requiresAuthorization": false
                }
            ],
            "serviceStartTime": "2020-03-04",
            "serviceEndTime": "2020-03-04",
            "validationErrors": []
        }
    ],
    "submittedAtUtc": "2020-03-04T05:52:48.893Z",
    "payee": {
        "reference": "test-payee-001",
        "name": "test-payee-001",
        "email": "test-payee-001@lanternpayabc.com",
        "abn": "12345678911",
        "bankAccount": {
            "bsb": "123456",
            "accountNumber": "231234",
            "accountHolder": "test-payee-001"
        }
    },
    "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/549be2f0-767d-4239-ac2a-a5c248414cda"
        },
        "curies": {
            "name": "lp",
            "href": "https://docs.lanternpay.com/reference#{rel}",
            "templated": true
        }
    },
    "invoiceKey": "549be2f0-767d-4239-ac2a-a5c248414cda",
    "invoiceDate": "2020-03-04",
    "invoiceNumber": "PM-API-384505964",
    "submittedAtUtc": "2020-03-04T00:00:00",
    "state": {
        "value": 3,
        "displayName": "Processed"
    },
    "biller": null,
    "totalClaimAmount": 150,
    "funded": 0,
    "claims": [
        {
            "claimKey": "107f0300-a0ad-46fd-a364-8930893d3477",
            "itemCode": "03_092406061_0103_1_1",
            "itemName": "Adult Intermittent Catheters Standard 3/Day - Annual Amount",
            "unitPriceIncTax": 100,
            "unitTax": 0,
            "quantity": {
                "units": 1,
                "duration": "0:00"
            },
            "totalPrice": 100,
            "totalClaimAmount": 100,
            "funded": 0,
            "taxCode": "FRE",
            "state": {
                "value": 5,
                "displayName": "Authorized"
            },
            "lineItemId": "PM-API-384505964-2",
            "fundingSources": [
                {
                    "insufficientContributionReasons": [],
                    "contribution": 100,
                    "requiresAuthorization": false,
                    "contractNumber": null,
                    "preauthorizationNumber": null,
                    "name": "NDIS"
                }
            ],
            "serviceStartTime": "2020-03-04",
            "serviceEndTime": "2020-03-04",
            "validationErrors": [],
            "ndisReference": "ce0ccf08-b879-474b-9d12-c72cb0291570"

        },
        {
            "claimKey": "ebbfe9f6-6299-4950-8aa1-00cf805d800b",
            "itemCode": "01_046_0115_1_1",
            "itemName": "Assistance In Individual Living Arrangement For Person With Complex Needs",
            "unitPriceIncTax": 50,
            "unitTax": 0,
            "quantity": {
                "units": 1,
                "duration": "0:00"
            },
            "totalPrice": 50,
            "totalClaimAmount": 50,
            "funded": 0,
            "taxCode": "FRE",
            "state": {
                "value": 5,
                "displayName": "Authorized"
            },
            "lineItemId": "PM-API-384505964-1",
            "fundingSources": [
                {
                    "insufficientContributionReasons": [],
                    "contribution": 50,
                    "requiresAuthorization": false,
                    "contractNumber": null,
                    "preauthorizationNumber": null,
                    "name": "NDIS"
                }
            ],
            "serviceStartTime": "2020-03-04",
            "serviceEndTime": "2020-03-04",
            "validationErrors": [],
            "ndisReference": "c72cbf08-b879-474b-9d12-ce0cc0291570"

        }
    ],
    "payee": {
        "reference": "test-payee-001",
        "name": "test-payee-001",
        "email": "test-payee-001@lanternpayabc.com",
        "abn": "12345678911",
        "bankAccount": {
            "bsb": "123456",
            "accountNumber": "231234",
            "accountHolder": "test-payee-001"
        }
    },
    "programCode": "ndis"
}

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 External Link 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 External Link 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"
                }
            ]
        }
    ]
}