^

Guides

Getting Started
  Introduction
  Your Business Settings
  Export From Other Systems
  Add An Employee
  Clocking Hours
  Timesheet Software
  Grouping Employees
  Management Configuration
  Locations

Rostering
  The Roster Process
  Roster Templates
  Roster Calendar
  Calendar View
  SMS Rosters

Timesheets
  The Timesheet Process
  Timesheet vs Roster
  Timesheet from Roster

Payroll
  The Payroll Process
  A Payrun
  Rate Rules
  Shift Rules
  Break Rules
  Deduction Rules
  Extra Rules
  Time In Lieu
  Public Holidays
  Jobs and Cost Centres

HR
  The Leave Request Process
  Leave Request Review
  Leave Payroll Process
  Skills Matrix

Reports
  Reports
  Single Touch Payroll
  Payment Summary
  Xero Integration

Other features
  Messaging

SuperChoice
  Processing Super

SuperChoice (Old process)
  Super Clearing House
  SuperChoice Setup
  Adding Super Fund
  Adding Employees
  Super Payment

Employees
  Employee Console
  Smartphone Login
  Push Notification
  Requesting Leave

Developers
  Partner Logo
  API Hello World
  API Employee
  API Timesheet
  API Payroll
  API Jobs
  API Roster

  Print Guide

Process and get payroll data via developer API


This guide explains how to process payroll via API while also allowing to add payments, expenses and deductions to the payroll process.



Before starting this tutorial make sure you have completed the Hello World tutorial.

To complete the Hello World tutorial click here  Hello World



Processing payroll via API

Processing payroll via API is very similar to processing payroll within Microkeeper.

The key difference is Payments, Expenses and Deductions can be automatically added via the API when the process is triggered.

This means all Shift rules, Rate rule, Extra rules, Deduction rules, super and leave will be applied as per normal.

This gives the 3rd party app the flexibility to select which parts of the payroll process they would like to handle and which parts Microkeeper will take care of.

Salary staff will be paid their standard salary without any payments sent via API.

Ad hoc payruns are not available via API but can be run within Microkeeper if required.

The API assumes Award Interpretation has taken place and just payment lines are being sent through.


Amendments

After the API has processed payroll:

- The user can add amendments to the payslip.

- The user can edit existing lines on the payslip.

- If a payrun is processed again via API all the added lines will remain but the edited lines will be replaced.

- If a payrun is processed again NOT via API all the lines that were added via API will be removed permanently.


Super

Super should not be sent as this will be calculated automatically based on the payments sent and classification of those payments.


Leave accrual and payments

Leave accrual process is automated by Microkeeper based on the hours paid and the employee's entitlement settings.

Leave can be paid out either through Microkeeper or as Payments sent via API.

Use this example table to set the note variable if paying out leave.

Note
Class
Mult
Annual Leave
Normal
1
Annual Loading
Extra
0.175
Sick Leave
Normal
1
Long Service Leave
Normal
1
RDO
Normal
1
TIL
Normal
1

RDO and TIL are grouped in Microkeeper.

The example above has the leave loading set to 17.5%.

As long as the note starts with the string it will be picked up, the search filter is "Annual Leave%".

Thus "Annual Leave" and "Annual Leave Job A" are treated the same.


Active staff

Only active staff are included in the payrun, meaning if no payments are sent for an Active employee a zero payslip will be created, which is fine.

In contrast, if payments are sent for terminated staff then the API will return an error for the entire request, the terminated staff should be fixed before the payrun can be processed.



Step 1

Set the mk_action variable and mk_data variable.

Variable name
Values and example
mk_action

add_payroll

mk_data
{ "config":{"start_date":"2018-12-01","end_date":"2018-12-31","payment_date":"2018-12-22","period":"semi-monthly"} ,
"pay_list":[{"EID":"3","eusername":"john_smith","note":"Basic Rate","rate":"15.123456789","hours":"38","mult":"1.25","JID":"2206","class":"normal","STP":""}] ,
"exp_list":[{"EID":"3","note":"Sal Sac","rate":"20","mult":"1","class":"Super"}] ,
"ded_list":[{"eusername":"john_smith","note":"Union","rate":"5","mult":"1","class":"Fees"}] }



Step 2

Payrun variables


Below is a list of variables that can be added to mk_data when adding payroll data.

Name
Classification
Note
config
Array
Config options when processing a payrun
pay_list
List
List of all the payments being added to the payrun
exp_list
List
List of all the expenses being added to the payrun
ded_list
List
List of all the deductions being added to the payrun


'config' variables

Variable name

Description

Required

Excepted formats

Options

start_date

The start of the pay period

True

Date YYYY-MM-DD

Currently no impact but required

end_date
The end of the pay period
True
Date YYYY-MM-DD

The end date is a run identifier, this lets Microkeeper know which payrun to process. For example, setting this value to YYYY-07-31 lets Microkeeper know it's the first month of the year, assuming monthly payroll is being processed.

This value is set by Microkeeper, if the end_date falls within a week then that week will be selected regardless if the end_date matches the end_date in Microkeeper If the end_date Microkeeper sets doesn't match the end_date being sent then this is a configuration issue in Microkeeper.

Review the Starting day of work setting in the Global settings.

payment_date
Replace start date
True
Date YYYY-MM-DD

The payment date is used to determine which month and fiscal year this payrun will fall into, this is critical to calculate super and EOFY reports correctly.

period
Replace end date
True
4 string options

weekly - Weekly payrun eg. Mon-Sun - 1st to 7th

fortnightly - Fortnightly payrun eg. Mon-Sun - 1st to 14th

semi-monthly - Semi-monthly payrun eg. 1st to 15th

monthly - Monthly payrun eg. 1st to 31st

runs_in_year
Is there an extra payrun this fiscal year? eg. 53 weeks
False
Boolean

0 = No extra run

1 = An extra run eg. 53 weeks or 27 fortnights

This is recommended for tax purposes. Not critical for a casual workforce.


The fields below can only be set the first time a payrun is processed, thus if the command is run again and the values have changed, the original values will be used.

period, runs_in_year, payment_date

If the payment date needs to be changed this can be done in Microkeeper.


'pay_list' variables

Variable name

Description

Required

Excepted formats

Example

EID

EmployeeID

TRUE or eusername

Numeric

1234

eusername

Employee username

TRUE or EID

Alphanumeric

john_smith

note

The description of the payment

TRUE

Alphanumeric

Max length: 50

JSON and URI can cause issues with apostrophe quotes and amps, make sure to test.

" = %26quot;

& = %26

' = should be fine might require escaping

OTE

Basic Rate

Ordinary Rate

Double Time

rate

Employee pay rate

Optional

Numeric

Negatives allowed

Rounded to 4 decimal places

25.00

Default in order:

Rate Rule

Employee Profile Rate

hours

The hours worked related to the payment line

Optional

Numeric

Rounded to 4 decimal places

Default 0

38

mult

The multiplier loading value. For example, time and a half enter 1.5

Optional

Numeric

Rounded to 4 decimal places

Default 1

1.25

It's best practice to add loading here.

For example, Casuals get a 25% loading, make 'mult' 1.25 rather than increase rate.

JID

Job ID in Microkeeper

Optional

Numeric

123456

class
Classification of payment
Optional
5 string options:

normal
overtime
bonus
extra
allowance


Not case sensitive

Default normal

Different classifications attract different rules

For example, extra does not get super

Refer to the Payments Classification Chart to learn more.


STP
Single Touch Payroll code
Optional
String

Case sensitive
It is likely this option will not be required as it can be filled from the Employees Profile.

If you do wish to fill this field refer to the STP guide.


If the hours line is set to 0 or omitted then it's skipped when calculating the total.

Example 

Bonus of $100, hours set to 0, mult set to 1, Thus total will be 100x1 = $100, not 100x0x1, which would = $0.

This is important so entitlements are not accrued.


'exp_list' variables

Variable name

Description

Required

Excepted formats

Example

EID

EmployeeID

TRUE or eusername

Numeric

1234

eusername

Employee username

TRUE or EID

Alphanumeric

john_smith

note

The description of the expense

TRUE

Alphanumeric

Max length: 30

JSON and URI can cause issues with apostrophe quotes and amps, make sure to test.

" = %26quot;

& = %26

' = should be fine might require escaping

Salary Sacrifice

rate

Employee expense value

TRUE

Numeric

Negatives allowed

Rounded to 3 decimal places

50.00

mult

The multiplier default 1

Optional

Numeric

Rounded to 2 decimal places

Default 1

class
Classification of expenses
Optional

3 string options:

''
super
fringe


Not case sensitive

Default '' {null}

Super for a Super Salary Sacrifice

Fringe for Fringe Benefit


'ded_list' variables

Variable name

Description

Required

Excepted formats

Example

EID

EmployeeID

TRUE or eusername

Numeric

1234

eusername

Employee username

TRUE or EID

Alphanumeric

john_smith

note

The description of the deduction

TRUE

Alphanumeric

Max length: 30

JSON and URI can cause issues with apostrophe quotes and amps, make sure to test.

" = %26quot;

& = %26

' = should be fine might require escaping

Union Fees

rate

Employee deduction value

TRUE

Numeric

Negatives allowed

Rounded to 3 decimal places

50.00

mult

The multiplier default 1

Optional

Numeric

Rounded to 2 decimal places

Default 1

class
Classification of deduction
Optional
4 string options:

''
fees
give
super


Not case sensitive

Default '' {null}

Fees for things like Union Fees

Give for workplace giving/charity

Super for a Super Deduction


Job ID (JID)

When Jobs are added to Microkeeper they are assigned a unique ID number. A JID can be sent via API when adding payments.

To get your Job ID numbers, go to:

Jobs > Jobs

Mouseover the ID number and a JID will be displayed.


Notes

The total for each line is rounded to 2 decimal places.



Step 3

Response

The response will be in JSON and in the format outlined in the Hello World example.

When a payrun is successfully processed in Microkeeper a successful message will be returned.

The message field could be displayed to the user as a confirmation.

A total for payments, expenses and deductions will be returned, this could be used for validation to ensure the total sent equals the total returned.

Note, the total on the payslip will likely not match the total sent as super and other payments might be added to the payslip, keep that in mind if the get_payroll API is called.


The below example is what would be returned if the request example above was processed.


Successful response example

{ "success":"1", "authenticated":"1", "message":"Payrun processed", "data": {"calculation_duration":0.31,"total":{"payment":718.37,"expense":20,"deduction":5}} }


Same example readable

Array
(
    [success] => 1
    [authenticated] => 1
    [message] => Payrun processed
    [data] => Array
        (
            [year] => 2018
            [run_id] => 312
            [calc_duration] => 0.31
            [total] => Array
                (
                    [payment] => 718.37
                    [expense] => 20
                    [deduction] => 5
                )
        )
)



Retrieving payroll data

Microkeeper payroll data can be exported from Microkeeper via API

All payroll data will be included via the date range supplied.

Up to 365 days of data can be exported in a single request.



Step 1

Set the mk_action variable and mk_data variable.

Variable name
Values and example
mk_action

get_payroll

mk_data

{ "start_date":"2018-05-21", "end_date":"2018-05-21" }



Step 2

List of available fields

Below is a list of variables that can be used to get payroll data.


Variable name

Description

Required

Excepted formats

Example

start_date

Start of the date range

TRUE

Date YYYY-MM-DD

2018-05-18

end_date

End of the date range

TRUE

Date YYYY-MM-DD

2018-05-23



Step 3

Response

A request will include a list of payruns.

Each payrun will include a list of Payslips.


'runs' variables [0]

Field name
Explanation
run_data
Array of specs for the payrun
payslips
Array of payslips


'run_data' variables


Field name
Explanation
Example
year

The fiscal year the payrun falls into based of period_end date
For 2018/2019 the year displayed will be 2018

2018
run_id

The run number in relation to the year
Weekly 1,2,3
Fortnight 2,4,6
Semi-monthly 301,302,303
Monthly 201,202,203
A combination of the year and run_id can be used to unique identity a run
run_id will reset at the start of every year

1
payment_date

The payment date as set by the employer
Format  YYYY-MM-DD

2018-10-20
wip

Weeks In Period
1=weekly
2=fortnightly
24=semi-monthly
12=monthly

12
period

weekly, fortnightly, semi-monthly, monthly

weekly
day

The starting day of the week, only relative to weekly and fortnightly pay

lowercase

wednesday
unlocked

Boolean, is the payrun locked or not

1
period_start

Start of the pay period
Format  YYYY-MM-DD

2018-10-08
period_end

End of the pay period
Format  YYYY-MM-DD

2018-10-14


'payslips' variables [0]

Field name
Explanation
Example
eusername
Employee username unique identifier
 john_smith
payment
Total payments for employee for payrun
234.88
expense
Total expenses for employee for payrun
170.38
taxable
Total taxable: taxable = payment-expense
64.50
deduction
Total deductions for an employee for payrun
10.00
tax
Total tax withheld
13.00
net
Total net: net = taxable-deduction-tax
41.50
hours
Hours worked for the period
12
annual
Annual leave balance as of this payrun, in hours
134.458
sick
Personal leave balance as of this payrun, in hours
205.867
rdo
RDO or TIL leave balance as of this payrun, in hours.
Note: RDO and TIL are stored in the same box in Microkeeper.
-3.334
lsl
Long Service Leave balance as of this payrun, in hours
151.88
EID
Employee ID unique identifier
3
pay_list
Array

exp_list
Array

ded_list
Array


'pay_list' variables [0]

Field name
Explanation
Example
note
Description of the payment
Basic Rate
JID
Job ID unique identifier
907
rate
Pay rate
20.5
hours
Hours paid for that line
9
mult
Multiplier
1
value
Total payment for that payment line
184.50
class
Classification of payment.
Refer to the Payments Classification Chart to learn more.

5 string options:
FALSE
TRUE
ALLOW
BONUS
EXTRA
FALSE
STP
Single Touch Payroll classifications
Refer to STP guide for a full list of codes
Note INB = blank
WHM


'exp_list' variables [0]

Field name
Explanation
Example
note
Description of the expenses
Super-Job C
rate
Expense rate
This will be a percentage if super guarantee or super above guarantee is exported, otherwise this will be a dollar value
9.500
mult
Multiplier
1
value
Total expense for that expense line
20.38
class
5 string options:
SUPER
SUPER2
SUPER3
FRINGE
'' {null} = Default
SUPER3


'ded_list' variables [0]

Field name
Explanation
Example
note
Description of the deduction
Super-Job C
rate
Deduction rate
9.500
mult
Multiplier
1
value
Total deduction for that deduction line
20.38
class
4 string options:
SUPER
GIVE
FEES
'' {null} = Default
FEES



Example payslip



Successful response example

This is an example of a single payrun with the single payslip created from the example above.

{ "success":"1", "authenticated":"1", "message":"Payrun data", "data": { "runs": [{"run_data":{"year":"2018","run_id":"5","payment_date":"2018-12-20","wip":"2","period":"fortnightly","day":"wednesday","unlocked":"1","period_start":"2018-07-18","period_end":"2018-07-31"},"payslips":[{"eusername":"john_smith","payment":"234.88","expense":"170.38","taxable":"64.50","deduction":"10.00","tax":"13.00","net":"41.50","hours":12,"annual":"134.458","sick":"205.867","rdo":"-3.334","lsl":"151.88","EID":"3",
"pay_list":[{"note":"Basic Job A","JID":"907","rate":"20.5","hours":"9","mult":"1","value":"184.50","class":"FALSE","STP":""},
{"note":"Fixed extra","JID":"909","rate":"10","hours":"3","mult":"1","value":"30.00","class":"TRUE","STP":""},
{"note":"Super Exclusive-Job C","JID":"909","rate":"9.5","hours":"0","mult":"0","value":"20.38","class":"SUPER","STP":""}],
"exp_list":[{"note":"Salary Sac","rate":"75.000","mult":"2.00","value":"150.00","class":"SUPER"},
{"note":"Super-Job C","rate":"9.500","mult":"1.00","value":"20.38","class":"SUPER3"}],
"ded_list":[{"note":"Test","rate":"10.000","mult":"1.00","value":"10.00","class":"FEES"}]}]}] } }


Same example readable

Array
(
    [success] => 1
    [authenticated] => 1
    [message] => Payrun data
    [data] => Array
        (
            [runs] => Array
                (
                    [0] => Array
                        (
                            [run_data] => Array
                                (
                                    [year] => 2018
                                    [run_id] => 5
                                    [payment_date] => 2018-12-20
                                    [wip] => 2
                                    [period] => fortnightly
                                    [day] => wednesday
                                    [unlocked] => 1
                                    [period_start] => 2018-07-18
                                    [period_end] => 2018-07-31
                                )
                            [payslips] => Array
                                (
                                    [0] => Array
                                        (
                                            [eusername] => john_smith
                                            [payment] => 234.88
                                            [expense] => 170.38
                                            [taxable] => 64.50
                                            [deduction] => 10.00
                                            [tax] => 13.00
                                            [net] => 41.50
                                            [hours] => 12
                                            [annual] => 134.458
                                            [sick] => 205.867
                                            [rdo] => -3.334
                                            [lsl] => 151.88
                                            [EID] => 3
                                            [pay_list] => Array
                                                (
                                                    [0] => Array
                                                        (
                                                            [note] => Basic Job A
                                                            [JID] => 907
                                                            [rate] => 20.5
                                                            [hours] => 9
                                                            [mult] => 1
                                                            [value] => 184.50
                                                            [class] => FALSE
                                                            [STP] =>
                                                        )
                                                    [1] => Array
                                                        (
                                                            [note] => Fixed extra
                                                            [JID] => 909
                                                            [rate] => 10
                                                            [hours] => 3
                                                            [mult] => 1
                                                            [value] => 30.00
                                                            [class] => TRUE
                                                            [STP] =>
                                                        )
                                                    [2] => Array
                                                        (
                                                            [note] => Super Exclusive-Job C
                                                            [JID] => 909
                                                            [rate] => 9.5
                                                            [hours] => 0
                                                            [mult] => 0
                                                            [value] => 20.38
                                                            [class] => SUPER
                                                            [STP] =>
                                                        )
                                                )
                                            [exp_list] => Array
                                                (
                                                    [0] => Array
                                                        (
                                                            [note] => Salary Sac
                                                            [rate] => 75.000
                                                            [mult] => 2.00
                                                            [value] => 150.00
                                                            [class] => SUPER
                                                        )
                                                    [1] => Array
                                                        (
                                                            [note] => Super-Job C
                                                            [rate] => 9.500
                                                            [mult] => 1.00
                                                            [value] => 20.38
                                                            [class] => SUPER3
                                                        )
                                                )
                                            [ded_list] => Array
                                                (
                                                    [0] => Array
                                                        (
                                                            [note] => Test
                                                            [rate] => 10.000
                                                            [mult] => 1.00
                                                            [value] => 10.00
                                                            [class] => FEES
                                                        )
                                                )
                                        )
                                )
                        )
                )
        )
)