Provider API

Overview

The Provider API is used to communicate between LanternPay and a Provider’s Practice Management System (PMS) for the purpose of submitting invoices and claims for a funding determination by the appropriate party.

Invoices and Claims

In LanternPay, a claim for payment is lodged by submitting an invoice. Each line-item on the invoice is an individual claim which represents a single item or service, identified by an item code. The item code must be recognised within the valid list of item codes for a specific program.

A simple invoice flow is outlined in the diagram below, from a user perspective as well as from the API perspective.

Invoice Submission Flow

Authentication

In general, all API calls to LanternPay need to be authenticated. LanternPay supports two authentication modes for the Provider API:

  1. Basic Authentication - generally for direct authentication with LanternPay, for example for use with a practice management system.
  2. OAuth Authentication - generally for user authorization where the user can use a web or mobile app to sign into LanternPay to authorize the application.

Unauthenticated or unauthorized requests generally will receive HTTP 401 - Unauthorized or HTTP 403 - Forbidden responses.

API credentials should be stored securely and never shared to prevent unauthorized access.

Basic Authentication

Basic authentication is common in cases where your application may not be able to have a user authorize access in real time and, as such, OAuth mechanisms are not suitable.

To use basic authentication, each user must have their own unique API key and API secret which can be requested directly from LanternPay. Your application should then offer a way for the users to configure their own keys under their profile.

To authorize a request, the Authorization Header must nominate the Basic authorization method, and the value must be a Base64 encoded string formed from the configured API key and API secret separated by a colon.

For example, if the API key is abc and the API secret is xyz then form the string abc:xyz. The base 64 encoding of this string is YWJjOnh5eg== so the authorization header must be: Authorization: Basic YWJjOnh5eg==

OAuth Authentication

The Provider API supports the OAuth 2.0 protocol. This protocol allows your application to access the Provider APIs on behalf of one of your users if they are a registered LanternPay user and they authorize your application’s access.

OAuth 2.0 supports a number of flows depending on the nature of your client application. LanternPay supports the Implicit Flows and Auth Code flows.

Flow Description
Implicit Best for Single Page Web Applications, Mobile Apps and Desktop Apps
Auth Code Best for traditional server-side Web Applications

When registering your client application, you will need to nominate which flow your client application will use.

See this page for an OAuth 2.0 tutorial and a more detailed overview of the different flows: http://tutorials.jenkov.com/oauth2/index.html

Client Application Identification

LanternPay requires the client application to identify itself, separately to identifying the authenticated user. This identifier is associated with a product, and ideally, a version of the product.

To identify your client application, each API request must include this HTTP header: X-LanternPay-Api-Client-Id

The value to include in the X-LanternPay-Api-Client-Id will be issued by LanternPay during onboarding. You will also be asked for the market-facing product name and version of your application.

The value included in the X-LanternPay-Api-Client-Id header should not be configurable by users of your application and the same value must be used for all requests from all installations, no matter which user the request is being made on behalf of.

If you release a new application version, you should request a new X-LanternPay-Api-Client-Id from LanternPay. This gives you more fine grained data reporting on which versions of your application are live and using the LanternPay APIs. It also gives you the opportunity to force retire old versions, by disabling a given X-LanternPay-Api-Client-Id.

If the header is not included, the response will be a HTTP 400 - Bad Request with a body message indicating that the header value must be supplied

Asynchronous Requests

The Provider API uses asynchronous requests for all non-safe requests (e.g. POST) - this means that the API will respond almost immediately with HTTP 202 - Accepted status on all async requests.

The location header will contain the URI of a resource that can be retrieved to check the status of the request - see Get a Request State for more info.

API Resources

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

Base URIs

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

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

Root

Get the API Root

GET /operations/claiming

The Provider API root resource is the start point for all API operations when using HATEOAS hypermedia to navigate the API. This resource can also be used to ensure connectivity with the Provider API.

Example Get the API Root Response

{
    "_links": {
        "self": {
            "href": "https://sandbox.lanternpay.com/api/operations/claiming",
            "method": "GET"
        },
        "lp:get-biller": {
            "href": "https://sandbox.lanternpay.com/api/operations/claiming/billers{?billerNumber}",
            "templated": true,
            "method": "GET"
        },
        "curies": [
            {
                "href": "https://sandbox.lanternpay.com/docs/{rel}",
                "templated": true,
                "name": "lp"
            }
        ]
    }
}

Billers

Find a Biller

GET /operations/claiming/billers?billerNumber={billerNumber}

Use this resource to search for a biller by biller number. The API response includes the lp:create-invoice link relation to create an invoice for the biller. The billerKey from the API response should be recorded to use when creating an invoice.

Path Parameters

Field Format Required? Description
billerNumber string Mandatory The biller number provided to the biller when they registered with LanternPay.

Example Find a Biller Response

{
    "name": "Sam's Physio",
    "number": "LP-BLR-12K3BR7I",
    "abn": "12345678901",
    "_links": {
        "self": {
            "href": "https://sandbox.lanternpay.com/api/operations/claiming/billers/2a865673-a011-0f95-10b9-e0117d789812",
            "method": "GET"
        },
        "lp:get-biller": {
            "href": "https://sandbox.lanternpay.com/api/operations/claiming/billers/2a865673-a011-0f95-10b9-e0117d789812",
            "method": "GET"
        },
        "lp:create-invoice": {
            "href": "https://sandbox.lanternpay.com/api/operations/claiming/billers/2a865673-a011-0f95-10b9-e0117d789812/invoices",
            "method": "POST"
        },
        "lp:list-invoices": {
            "href": "https://sandbox.lanternpay.com/api/operations/claiming/billers/2a865673-a011-0f95-10b9-e0117d789812/invoices{?fromDate,toDate,invoiceNumber,search,offset,pageSize}",
            "templated": true,
            "method": "GET"
        },
        "curies": [
            {
                "href": "https://sandbox.lanternpay.com/docs/{rel}",
                "templated": true,
                "name": "lp"
            }
        ]
    },
    "_embedded": {
        "lp:programs": [
            {
                "name": "National Disability Insurance Scheme",
                "code": "ndis",
                "_links": {
                    "self": {
                        "href": "https://sandbox.lanternpay.com/api/operations/claiming/programs/f26db9dc-3287-093d-17a7-3df05c3165d2",
                        "method": "GET"
                    },
                    "curies": [
                        {
                            "href": "https://sandbox.lanternpay.com/docs/{rel}",
                            "templated": true,
                            "name": "lp"
                        }
                    ]
                }
            }
        ]
    }
}

Get a Biller

GET /operations/claiming/billers/{billerKey}

Use this resource to view a biller resource by billerKey. The API response includes the lp:create-invoice link relation to create an invoice for the biller.

Path Parameters

Field Format Required? Description
billerKey UUID Mandatory The unique biller reference provided by LanternPay. FInd this resource in the lp:get-biller link relation on the Find a Biller API response.

Example Get a Biller Response

{
    "name": "Sam's Physio",
    "number": "LP-BLR-12K3BR7I",
    "abn": "12345678901",
    "_links": {
        "self": {
            "href": "https://sandbox.lanternpay.com/api/operations/claiming/billers/2a865673-a011-0f95-10b9-e0117d789812",
            "method": "GET"
        },
        "lp:get-biller": {
            "href": "https://sandbox.lanternpay.com/api/operations/claiming/billers/2a865673-a011-0f95-10b9-e0117d789812",
            "method": "GET"
        },
        "lp:create-invoice": {
            "href": "https://sandbox.lanternpay.com/api/operations/claiming/billers/2a865673-a011-0f95-10b9-e0117d789812/invoices",
            "method": "POST"
        },
        "lp:list-invoices": {
            "href": "https://sandbox.lanternpay.com/api/operations/claiming/billers/2a865673-a011-0f95-10b9-e0117d789812/invoices{?fromDate,toDate,invoiceNumber,search,offset,pageSize}",
            "templated": true,
            "method": "GET"
        },
        "curies": [
            {
                "href": "https://sandbox.lanternpay.com/docs/{rel}",
                "templated": true,
                "name": "lp"
            }
        ]
    },
    "_embedded": {
        "lp:programs": [
            {
                "name": "National Disability Insurance Scheme",
                "code": "ndis",
                "_links": {
                    "self": {
                        "href": "https://sandbox.lanternpay.com/api/operations/claiming/programs/f26db9dc-3287-093d-17a7-3df05c3165d2",
                        "method": "GET"
                    },
                    "curies": [
                        {
                            "href": "https://sandbox.lanternpay.com/docs/{rel}",
                            "templated": true,
                            "name": "lp"
                        }
                    ]
                }
            }
        ]
    }
}

Invoices

List Invoices for a Biller

GET /operations/claiming/billers/{billerKey}/invoices?{queryParameters}

Use this resource to return a list of invoices for a biller, with optional filters that can be applied to the query to refine the results.

Path Parameters

Field Format Required? Description
billerKey UUID Mandatory The unique biller reference provided by LanternPay. Find this resource in the lp:resource link relation of the Get a Biller API response.

Query Parameters

Field Format Required? Description
fromDate date - YYYY-MM-DD Optional Filter the results to show invoices after the this date.
toDate date - YYYY-MM-DD Optional Filter the results to show invoices before the this date.
invoiceNumber string Optional Filter the results to show invoices with this invoice number.
offset integer Optional Starting from 0 the offset allows pagination of the results.
pageSize integer Optional The number of invoices to return as a single page in the results.

Example List Invoices for a Biller Response

{
    "pageSize": 10,
    "offset": 0,
    "total": 2,
    "_links": {
        "self": {
            "href": "https://sandbox.lanternpay.com/api/operations/claiming/billers/1a265673-a011-0f95-10c9-e0117d789812/invoices?fromDate=2019-07-05&toDate=2019-07-11&offset=0&pageSize=10",
            "method": "GET"
        },
        "lp:first": {
            "href": "https://sandbox.lanternpay.com/api/operations/claiming/billers/1a265673-a011-0f95-10c9-e0117d789812/invoices?fromDate=2019-07-05&toDate=2019-07-11&offset=0&pageSize=10",
            "method": "GET"
        },
        "lp:last": {
            "href": "https://sandbox.lanternpay.com/api/operations/claiming/billers/1a265673-a011-0f95-10c9-e0117d789812/invoices?fromDate=2019-07-05&toDate=2019-07-11&offset=0&pageSize=10",
            "method": "GET"
        },
        "curies": [
            {
                "href": "https://sandbox.lanternpay.com/docs/{rel}",
                "templated": true,
                "name": "lp"
            }
        ]
    },
    "_embedded": {
        "lp:invoices": [
            {
                "invoiceKey": "79ee233a-547a-01a5-03da-1e1a44390c9f",
                "programCode": "ndis",
                "client": {
                    "dateOfBirth": "1950-11-21",
                    "programClientNumber": "08260628263"
                },
                "invoiceDate": "2019-07-11",
                "invoiceNumber": "P-API-346880588",
                "state": {
                    "value": 3,
                    "displayName": "Processed"
                },
                "totalClaimAmount": 150,
                "funded": 150,
                "unfunded": 0,
                "validationErrors": [],
                "createdAtUtc": "2019-07-11T06:44:06.54",
                "submittedAtUtc": "2019-07-11T06:44:42.353",
                "claims": [
                    {
                        "lineItemId": "P-API-346880588-1",
                        "serviceProvider": {
                            "lanternPayServiceProviderNumber": "",
                            "medicareProviderNumber": "",
                            "ahpraRegistrationNumber": "",
                            "firstName": "Sam",
                            "lastName": "Smith"
                        },
                        "itemCode": "01_001_0101_1_1",
                        "itemName": "Transitional Support",
                        "unitPriceIncTax": 50,
                        "unitTax": 0,
                        "quantity": {
                            "units": "2.0000",
                            "duration": null
                        },
                        "totalPrice": 100,
                        "totalClaimAmount": 100,
                        "funded": 100,
                        "unfunded": 0,
                        "taxCode": "FRE",
                        "state": {
                            "value": 5,
                            "displayName": "Authorization Required"
                        },
                        "fundingSources": [
                            {
                                "name": "ndis",
                                "contribution": 100,
                                "requiresClientAuthorization": true,
                                "insufficientContributionReasons": []
                            }
                        ],
                        "serviceStartTime": "2019-06-21",
                        "serviceEndTime": "2019-06-21",
                        "description": "First example description.",
                        "validationErrors": []
                    },
                    {
                        "lineItemId": "P-API-346880588-2",
                        "serviceProvider": {
                            "lanternPayServiceProviderNumber": "",
                            "medicareProviderNumber": "",
                            "ahpraRegistrationNumber": "",
                            "firstName": "Sam",
                            "lastName": "Smith"
                        },
                        "itemCode": "01_001_0101_1_1",
                        "itemName": "Transitional Support",
                        "unitPriceIncTax": 50,
                        "unitTax": 0,
                        "quantity": {
                            "units": "1.0000",
                            "duration": null
                        },
                        "totalPrice": 50,
                        "totalClaimAmount": 50,
                        "funded": 50,
                        "unfunded": 0,
                        "taxCode": "FRE",
                        "state": {
                            "value": 5,
                            "displayName": "Authorization Required"
                        },
                        "fundingSources": [
                            {
                                "name": "ndis",
                                "contribution": 50,
                                "requiresClientAuthorization": true,
                                "insufficientContributionReasons": []
                            }
                        ],
                        "serviceStartTime": "2019-06-20",
                        "serviceEndTime": "2019-06-20",
                        "description": "Second example description.",
                        "validationErrors": []
                    }
                ],
                "_links": {
                    "self": {
                        "href": "https://sandbox.lanternpay.com/api/operations/claiming/invoices/79ee233a-547a-01a5-03da-1e1a44390c9f",
                        "method": "GET"
                    },
                    "curies": [
                        {
                            "href": "https://sandbox.lanternpay.com/docs/{rel}",
                            "templated": true,
                            "name": "lp"
                        }
                    ]
                }
            },
            {
                "invoiceKey": "fecd6031-79f0-0321-11d5-3d338732bdce",
                "programCode": "ndis",
                "client": {
                    "dateOfBirth": "1950-11-21",
                    "programClientNumber": "08260628263"
                },
                "invoiceDate": "2019-07-11",
                "invoiceNumber": "P-API-311657719",
                "state": {
                    "value": 3,
                    "displayName": "Processed"
                },
                "totalClaimAmount": 150,
                "funded": 150,
                "unfunded": 0,
                "validationErrors": [],
                "createdAtUtc": "2019-07-11T04:28:44.727",
                "submittedAtUtc": "2019-07-11T04:28:49.103",
                "claims": [
                    {
                        "lineItemId": "P-API-311657719-1",
                        "serviceProvider": {
                            "lanternPayServiceProviderNumber": "",
                            "medicareProviderNumber": "",
                            "ahpraRegistrationNumber": "",
                            "firstName": "Sam",
                            "lastName": "Smith"
                        },
                        "itemCode": "01_001_0101_1_1",
                        "itemName": "Transitional Support",
                        "unitPriceIncTax": 50,
                        "unitTax": 0,
                        "quantity": {
                            "units": "2.0000",
                            "duration": null
                        },
                        "totalPrice": 100,
                        "totalClaimAmount": 100,
                        "funded": 100,
                        "unfunded": 0,
                        "taxCode": "FRE",
                        "state": {
                            "value": 5,
                            "displayName": "Authorization Required"
                        },
                        "fundingSources": [
                            {
                                "name": "ndis",
                                "contribution": 100,
                                "requiresClientAuthorization": true,
                                "insufficientContributionReasons": []
                            }
                        ],
                        "serviceStartTime": "2019-06-21",
                        "serviceEndTime": "2019-06-21",
                        "description": "First example description.",
                        "validationErrors": []
                    },
                    {
                        "lineItemId": "P-API-311657719-2",
                        "serviceProvider": {
                            "lanternPayServiceProviderNumber": "",
                            "medicareProviderNumber": "",
                            "ahpraRegistrationNumber": "",
                            "firstName": "Sam",
                            "lastName": "Smith"
                        },
                        "itemCode": "01_001_0101_1_1",
                        "itemName": "Transitional Support",
                        "unitPriceIncTax": 50,
                        "unitTax": 0,
                        "quantity": {
                            "units": "1.0000",
                            "duration": null
                        },
                        "totalPrice": 50,
                        "totalClaimAmount": 50,
                        "funded": 50,
                        "unfunded": 0,
                        "taxCode": "FRE",
                        "state": {
                            "value": 5,
                            "displayName": "Authorization Required"
                        },
                        "fundingSources": [
                            {
                                "name": "ndis",
                                "contribution": 50,
                                "requiresClientAuthorization": true,
                                "insufficientContributionReasons": []
                            }
                        ],
                        "serviceStartTime": "2019-06-20",
                        "serviceEndTime": "2019-06-20",
                        "description": "Second example description.",
                        "validationErrors": []
                    }
                ],
                "_links": {
                    "self": {
                        "href": "https://sandbox.lanternpay.com/api/operations/claiming/invoices/fecd6031-79f0-0321-11d5-3d338732bdce",
                        "method": "GET"
                    },
                    "curies": [
                        {
                            "href": "https://sandbox.lanternpay.com/docs/{rel}",
                            "templated": true,
                            "name": "lp"
                        }
                    ]
                }
            }
        ]
    }
}

Create an Invoice

POST /operations/claiming/billers/{billerKey}/invoices

This resources allows the creation of draft invoices, which includes an initial analysis of each claim. The invoiceKey from the API response should be recorded to use when submitting an invoice. The draft invoice will only be submittable for processing if the initial analysis has determined that no claimed amounts are unfunded.

Note: This is an asynchronous request. Poll the Request State API to await processing completion.

Path Parameters

Field Format Required? Description
billerKey UUID Mandatory The unique biller reference provided by LanternPay. Find this resource from the lp:create-invoice link relation in the Find a Biller API response.

Body Parameters

Field Format Required? Description
programCode string Mandatory The program code for this invoice. Can be obtained from the lp:programs resource in the Find a Biller API response.
client object Mandatory The client identification details. See table below.
invoiceDate string Mandatory The invoice date as per the biller’s records.
invoiceNumber string Mandatory The invoice number as per the biller’s records. Does not need to be unique.
claims array of objects Mandatory The array of claims, or line items, on the invoice. See table below.

Client Parameters

Field Format Required? Description
dateOfBirth date - YYYY-MM-DD Mandatory The client’s date of birth.
programClientNumber string Mandatory The client’s identification or membership number with the program.

Claims Parameters

Field Format Required? Description
lineItemId string
serviceProvider object The service provider identification details. See table below.
itemCode string
unitPriceIncTax
UnitTax
taxCode string
quantity object The quantity of the item for the claim. This is multiplied by the unit price to get the total value of the claim. See table below.
totalClaimAmount
serviceStartTime string
serviceEndTime string
description string

serviceProvider Parameters

Note: In the table below, only one of lanternPayServiceProviderNumber, medicareProviderNumber or ahpraRegistrationNumber is required.

Field Format Required? Description
lanternPayServiceProviderNumber string Conditional The LanternPay issued provider number.
medicareProviderNumber string Conditional The provider’s Medicare provider number.
ahpraRegistrationNumber string Conditional The provider’s AHPRA registration number.
firstName string Mandatory The first name of the service provider.
lastName string Mandatory The last name of the service provider.

Quantity Parameters

Note: In the table below, only one of units or duration may be used. Do not specify both.

Field Format Required? Description
units decimal (2dp) Conditional The unit quantity for the service provided.
duration time - HHH:MM Conditional The time quantity for the service provided.

Example Create an Invoice Request

{
	"programCode": "ndis",
	"client": {
		"dateOfBirth": "1950-01-01",
		"programClientNumber": "123456789"
	},
	"invoiceDate": "2019-06-01",
	"invoiceNumber": "INV123456789",
	"claims": [
		{
			"lineItemId": "INV123456789-1",
			"serviceProvider": {
				"lanternPayServiceProviderNumber": "",
				"medicareProviderNumber": "",
				"ahpraRegistrationNumber": "",
				"firstName": "Sam",
				"lastName": "Smith"
			},
			"itemCode": "01_001_0101_1_1",
			"unitPriceIncTax": 50,
			"unitTax": 0,
			"taxCode": "FRE",
			"quantity": {
				"units": "2.00",
				"duration": ""				
			},
			"totalClaimAmount": 100,
			"serviceStartTime": "2019-06-21",
			"serviceEndTime": "2019-06-21",
			"description": "First example description."
		},
		{
			"lineItemId": "INV123456789-2",
			"serviceProvider": {
				"lanternPayServiceProviderNumber": "",
				"medicareProviderNumber": "",
				"ahpraRegistrationNumber": "",
				"firstName": "Sam",
				"lastName": "Smith"
			},
			"itemCode": "01_001_0101_1_1",
			"unitPriceIncTax": "50.00",
			"unitTax": "0",
			"taxCode": "FRE",
			"quantity": {
				"units": "1.00"
			},
			"totalClaimAmount": "50.00",
			"serviceStartTime": "2019-06-20",
			"serviceEndTime": "2019-06-20",
			"description": "Second example description."
		}
	]
}

Example Create an Invoice Response

This is an asynchronous request, so you will receive HTTP 202 - Accepted if LanternPay receives the request successfully. Poll the Request State API to await processing completion.

{
    "key": "90c0bd19-6829-00a9-115a-617d7ec5aafb",
    "requestKey": "90c0bd19-6829-00a9-115a-617d7ec5aafb",
    "resourceUri": "https://sandbox.lanternpay.com/api/operations/claiming/invoices/7c31c5d6-f689-08d9-2351-a23bef92250e",
    "callbackSignalRGroup": "RequestCompleteCallbackGroup:edb4ab85-4d54-409f-a9da-43d0a9b0b36b",
    "isComplete": true,
    "hasErrors": false,
    "failed": false,
    "state": {
        "value": 3,
        "displayName": "Completed Successfully"
    },
    "errors": [],
    "operations": {
        "pending": 0,
        "completed": 2,
        "failed": 0
    },
    "_links": {
        "self": {
            "href": "https://sandbox.lanternpay.com/api/requests/90c0bd19-6829-00a9-115a-617d7ec5aafb",
            "method": "GET"
        },
        "lp:resource": {
            "href": "https://sandbox.lanternpay.com/api/operations/claiming/invoices/7c31c5d6-f689-08d9-2351-a23bef92250e",
            "method": "GET"
        },
        "curies": [
            {
                "href": "https://sandbox.lanternpay.com/docs/{rel}",
                "templated": true,
                "name": "lp"
            }
        ]
    }
}

Submit an Invoice

POST /operations/claiming/invoices/{invoiceKey}/submit

This resource allows submission of a previously created draft invoice for processing. The draft invoice will only be submittable if the initial analysis has determined that no claimed amounts are unfunded.

Note: This is an asynchronous request. Poll the Request State API to await processing completion.

Path Parameters

Field Format Required? Description
invoiceKey UUID Mandatory The unique invoice reference provided by LanternPay in the Create an Invoice API response. Find this resource on the lp:submit link relation on the Create an Invoice API response.

Example Submit an Invoice Response

This is an asynchronous request, so you will receive HTTP 202 - Accepted and the below JSON body if LanternPay receives the request successfully. Poll the Request State API to await processing completion.

{
    "key": "7dd4a1fe-8ed6-0a32-27c8-2e657ddde421",
    "requestKey": "7dd4a1fe-8ed6-0a32-27c8-2e657ddde421",
    "resourceUri": "https://sandbox.lanternpay.com/api/operations/claiming/invoices/7c31c5d6-f689-08d9-2351-a23bef92250e",
    "callbackSignalRGroup": "RequestCompleteCallbackGroup:197287ba-6755-4ee8-a761-592df00432d1",
    "isComplete": false,
    "hasErrors": false,
    "failed": false,
    "state": {
        "value": 2,
        "displayName": "In Progress"
    },
    "errors": [],
    "operations": {
        "pending": 3,
        "completed": 1,
        "failed": 0
    },
    "_links": {
        "self": {
            "href": "https://sandbox.lanternpay.com/api/requests/7dd4a1fe-8ed6-0a32-27c8-2e657ddde421",
            "method": "GET"
        },
        "curies": [
            {
                "href": "https://sandbox.lanternpay.com/docs/{rel}",
                "templated": true,
                "name": "lp"
            }
        ]
    }
}

Cancel an Invoice

POST /operations/claiming/invoices/{invoiceKey}/cancel

Use this resource to cancel an invoice so it will not be paid. Not all invoices are cancellable, depending on individual program rules.

Note: This is an asynchronous request. Poll the Request State API to await processing completion.

Path Parameters

Field Format Required? Description
invoiceKey UUID Mandatory The unique invoice reference provided by LanternPay in the Create an Invoice API response. Find this resource on the lp:cancel link relation on the Get an Invoice API response.

Example Cancel an Invoice Response

This is an asynchronous request, so you will receive HTTP 202 - Accepted if LanternPay receives the request successfully. Poll the Request State API to await processing completion.

If the invoice is not cancellable, you will receive HTTP 404 - Not Found and the below response body.

{
    "message": "This invoice is not cancellable."
}

Get an Invoice

GET /operations/claiming/invoices/{invoiceKey}

Use this resource to view an individual invoice to check its status and funding availability.

Path Parameters

Field Format Required? Description
invoiceKey UUID Mandatory The unique invoice reference provided by LanternPay in the Create an Invoice API response. Find this resource on the lp:resource link relation on the Create an Invoice API response.

Example Get an Invoice Response

{
    "invoiceKey": "7c31c5d6-f689-08d9-2351-a23bef92250e",
    "programCode": "ndis",
    "client": {
        "dateOfBirth": "1950-11-21",
        "programClientNumber": "08260628263"
    },
    "invoiceDate": "2019-07-12",
    "invoiceNumber": "P-API-289301127",
    "state": {
        "value": 3,
        "displayName": "Processed"
    },
    "totalClaimAmount": 150,
    "funded": 150,
    "unfunded": 0,
    "validationErrors": [],
    "createdAtUtc": "2019-07-12T01:22:49.667",
    "submittedAtUtc": "2019-07-12T01:22:49.99",
    "claims": [
        {
            "lineItemId": "P-API-289301127-1",
            "serviceProvider": {
                "lanternPayServiceProviderNumber": "",
                "medicareProviderNumber": "",
                "ahpraRegistrationNumber": "",
                "firstName": "Sam",
                "lastName": "Smith"
            },
            "itemCode": "01_001_0101_1_1",
            "itemName": "Transitional Support",
            "unitPriceIncTax": 50,
            "unitTax": 0,
            "quantity": {
                "units": "2.0000",
                "duration": null
            },
            "totalPrice": 100,
            "totalClaimAmount": 100,
            "funded": 100,
            "unfunded": 0,
            "taxCode": "FRE",
            "state": {
                "value": 5,
                "displayName": "Authorization Required"
            },
            "fundingSources": [
                {
                    "name": "ndis",
                    "contribution": 100,
                    "requiresClientAuthorization": true,
                    "insufficientContributionReasons": []
                }
            ],
            "serviceStartTime": "2019-06-21",
            "serviceEndTime": "2019-06-21",
            "description": "First example description.",
            "validationErrors": []
        },
        {
            "lineItemId": "P-API-289301127-2",
            "serviceProvider": {
                "lanternPayServiceProviderNumber": "",
                "medicareProviderNumber": "",
                "ahpraRegistrationNumber": "",
                "firstName": "Sam",
                "lastName": "Smith"
            },
            "itemCode": "01_001_0101_1_1",
            "itemName": "Transitional Support",
            "unitPriceIncTax": 50,
            "unitTax": 0,
            "quantity": {
                "units": "1.0000",
                "duration": null
            },
            "totalPrice": 50,
            "totalClaimAmount": 50,
            "funded": 50,
            "unfunded": 0,
            "taxCode": "FRE",
            "state": {
                "value": 5,
                "displayName": "Authorization Required"
            },
            "fundingSources": [
                {
                    "name": "ndis",
                    "contribution": 50,
                    "requiresClientAuthorization": true,
                    "insufficientContributionReasons": []
                }
            ],
            "serviceStartTime": "2019-06-20",
            "serviceEndTime": "2019-06-20",
            "description": "Second example description.",
            "validationErrors": []
        }
    ],
    "_links": {
        "self": {
            "href": "https://sandbox.lanternpay.com/api/operations/claiming/invoices/7c31c5d6-f689-08d9-2351-a23bef92250e",
            "method": "GET"
        },
        "lp:get-biller": {
            "href": "https://sandbox.lanternpay.com/api/operations/claiming/billers/1a865673-a011-0f95-10b9-e0117d789812",
            "method": "GET"
        },
        "curies": [
            {
                "href": "https://sandbox.lanternpay.com/docs/{rel}",
                "templated": true,
                "name": "lp"
            }
        ]
    }
}

Programs

Get a Program

GET /operations/claiming/programs/{programKey}

The program resource allows you to discover the appropriate programCode to use when creating an invoice. It is also available as an embedded resource on the Get a Biller API response.

Path Parameters

Field Format Required? Description
programKey UUID Mandatory The unique program reference provided by LanternPay. Find this resource on the lp:programs link relation on the Find a Biller API response.

Example Get a Program Response

{
    "name": "National Disability Insurance Scheme",
    "code": "ndis",
    "_links": {
        "self": {
            "href": "https://sandbox.lanternpay.com/api/operations/claiming/programs/f26db9dc-3287-093d-17a7-3df05c3165d2",
            "method": "GET"
        },
        "curies": [
            {
                "href": "https://sandbox.lanternpay.com/docs/{rel}",
                "templated": true,
                "name": "lp"
            }
        ]
    }
}

Request State

Get a Request State

GET /requests/{requestKey}

Use this resource to check on the status of an asynchronous request. Look for the isComplete property and the presence of an lp:resource link relation to know it is finished. Follow the lp:resource link relation to obtain the resource that was created or updated by this request.

Path Parameters

Field Format Required? Description
requestKey UUID Mandatory The unique request reference provided by LanternPay for any asynchronous request. Find this resource in the self link relation in the API response to any asynchronous API request.

Example Get a Request State Response

{
    "key": "af275328-7d01-0502-3c92-5486cd0ce6bc",
    "requestKey": "af275328-7d01-0502-3c92-5486cd0ce6bc",
    "resourceUri": "https://sandbox.lanternpay.com/api/operations/claiming/invoices/926f0098-3209-0fc9-18bb-929d710aac19",
    "callbackSignalRGroup": "RequestCompleteCallbackGroup:7265eb9d-8baf-46db-a8cb-f7d36ba8f86e",
    "isComplete": true,
    "hasErrors": false,
    "failed": false,
    "state": {
        "value": 3,
        "displayName": "Completed Successfully"
    },
    "errors": [],
    "operations": {
        "pending": 0,
        "completed": 4,
        "failed": 0
    },
    "_links": {
        "self": {
            "href": "https://sandbox.lanternpay.com/api/requests/af275328-7d01-0502-3c92-5486cd0ce6bc",
            "method": "GET"
        },
        "lp:resource": {
            "href": "https://sandbox.lanternpay.com/api/operations/claiming/invoices/926f0098-3209-0fc9-18bb-929d710aac19",
            "method": "GET"
        },
        "curies": [
            {
                "href": "https://sandbox.lanternpay.com/docs/{rel}",
                "templated": true,
                "name": "lp"
            }
        ]
    }
}