The 'Lodgement Messages' feature allows you to view the raw data sent to the ATO in relation to pay event details, and can be used to gain more detail about a pay event than what is shown on the Reports > Single Touch Payroll page.
N.B. The length of time that message logs are kept is the start of the previous financial year. E.g. in the 19/20 financial year, message logs will date back to 1/7/2018.
Some reasons to use this feature include, but are not limited to:
- if you need to track down employee personal and TFN details that were reported at the time of a specific lodgement;
- to determine who lodged the pay event and the reporting party type;
the BMS ID and ABN for each employing entity involved in the lodgement.
To access this feature, firstly search for the business in question and then click on the 'Lodgement Messages' menu option:
The three filter options to be aware of are:
- Date range - select a range that covers the date submitted for the pay event in question.
- Message types - You can select from 'Pay event request' (our requests to the ATO) and 'Poll pay event request' (ATO responses). Alternatively leave it at 'all message types' to look at both.
- Search terms - If you know the message ID you can enter it here directly. The message ID is the 'Receipt number' that is shown on the 'Lodgement details' tab of the pay event.
Depending on the number of results, you may need to scroll down to the bottom of the page and navigate to the next page. There is a limit of 20 records per page.
Interpreting the results
The 'PayEventRequest' message type will contain the data as it was at the time of lodging the event, and this is the data that is sent from the payroll system across to the ATO. It will show the details for each employee included in the pay event and the business details as at the time of submission. The response column for the 'PayEventRequest' will also confirm whether or not the event was delivered, and whether (at that point) any errors were evident.
When the ATO have responded, there will be a 'PollPayEventRequest' message type, and this will contain more details about any errors that have been detected and what data was being sent at the time. Any errors here will also be shown on the Reports > STP page and more information about specific errors can be found here.
Stuck pay runs
A pay event might become stuck if:
- the connection between KeyPay and the ATO is disrupted
- our upstream provider has issues
- repeated failed attempts to retrieve a message from the ATO will result in the system giving up but not in an orderly fashion (ie. failing the event with the error message "Retry limit reached"
- the ATO are just not responding to our request - the event won't fail, it'll be stuck but the Lodgement Message Log will show: ErrorMessage": "EmptyMessagePartitionChannel"
- the ATO only let us retrieve a response for a pay event once, so if we don't get it the first time it's offered, the message is not retrievable and our repeated attempts to get it again may result in the pay event getting stuck (because after numerous failed attempts the system simply stops trying).
If a pay run is stuck, you may see any of these errors in the 'Response' column...
- "Message": "Response status code does not indicate success: 500 (Internal Server Error)." -- KeyPay issue
- "Message": "A task was cancelled." -- KeyPay issue
- "Message": "An error occurred while sending the request." -- KeyPay issue
- "ErrorMessage": "No receipt in signal messages" -- KeyPay issue
- "ErrorMessage": "EBMS Errors" -- should no longer see this
- "ErrorMessage": "EmptyMessagePartitionChannel" -- there is no response to our poll request. Either the ATO has not processed the Pay Event or something has failed along the way. Could be the ATO, Holodeck or KeyPay.
These instances require manual intervention so you'll need to contact firstname.lastname@example.org with the details.
If you have any questions, please contact your payroll champion, and if needed they can contact us via email@example.com