^ Login

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.


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 via API, any lines that were previously includes are replaced with the new data.

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

NoteClassMult
Annual Leave-Normal1
Annual Loading-Extra0.175
Sick Leave-Normal1
Long Service Leave-Normal1
RDO-Normal1
TIL-Normal1

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

By default only staff that are being sent through are included in the payrun.

Example, if there are 1000 active staff but only 100 staff are receiving a payment 100 payslips will be generated.


active_staff = true

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.

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.


Locked Payruns

Once a payrun is locked it can not be processes again via API, this is to prevent accidentally processing historical payruns.

If a payrun needs to be processed again it can be unlocked, we recommend download a backup of the payslips before hand especially if staff have already been paid.


Step 1

Set the mk_action variable and mk_data variable.

Variable nameValues 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.

NameClassificationNote
configArrayConfig options when processing a payrun
pay_listListList of all the payments being added to the payrun
exp_listListList of all the expenses being added to the payrun
ded_listListList 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

YYYY-MM-DD

Currently no impact but required

end_dateThe end of the pay periodTrueYYYY-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_dateReplace start dateTrueYYYY-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.

periodReplace end dateTrue4 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_yearIs there an extra payrun this fiscal year? eg. 53 weeksFalseBoolean
0 = No extra run (default)

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

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

active_staffDo you want to include all active staffFalseBoolean
0 = Only staff that are receiving a payment or deduction will be included

1 = All staff are included, recommended if you are using Microkeeper for some staff and API for other staff


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

MK Employee ID

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.

dateDate the payment refers toOptionalYYYY-MM-DD2021-12-20

LID

Location ID in Microkeeper

Optional

Numeric

111222

ROID

Role ID in Microkeeper

Optional

Numeric

125476

JID

Job ID in Microkeeper

Optional

Numeric

123456

classClassification of paymentOptional5 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.


STPSingle Touch Payroll codeOptionalString

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

MK Employee ID

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

classClassification of expensesOptional
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

MK Employee ID

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

classClassification of deductionOptional4 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 nameValues 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

Accepted Formats

Example

start_date

Start of the date range

TRUE

YYYY-MM-DD

2018-05-18

end_date

End of the date range

TRUE

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 nameExplanation
run_dataArray of specs for the payrun
payslipsArray of payslips


'run_data' variables


Field nameExplanationExample
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 nameExplanationExample
eusernameEmployee username unique identifier john_smith
paymentTotal payments for employee for payrun234.88
expenseTotal expenses for employee for payrun170.38
taxableTotal taxable: taxable = payment-expense64.50
deductionTotal deductions for an employee for payrun10.00
taxTotal tax withheld13.00
netTotal net: net = taxable-deduction-tax41.50
hoursHours worked for the period12
annualAnnual leave balance as of this payrun, in hours134.458
sickPersonal leave balance as of this payrun, in hours205.867
rdoRDO or TIL leave balance as of this payrun, in hours.
Note: RDO and TIL are stored in the same box in Microkeeper.
-3.334
lslLong Service Leave balance as of this payrun, in hours151.88
EIDMK Employee ID unique identifier3
EmployeeIDThird party ID unique identifierABC123
pay_listArray
exp_listArray
ded_listArray


'pay_list' variables [0]

Field nameExplanationExample
noteDescription of the paymentBasic Rate
dateDate the payment refers to2021-12-20
LIDLocation ID321
ROIDRole ID517
JIDJob ID907
ratePay rate20.5
hoursHours paid for that line9
multMultiplier1
valueTotal payment for that payment line184.50
classClassification of payment.
Refer to the Payments Classification Chart to learn more.

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


'exp_list' variables [0]

Field nameExplanationExample
noteDescription of the expensesSuper-Job C
rateExpense rate
This will be a percentage if super guarantee or super above guarantee is exported, otherwise this will be a dollar value
9.500
multMultiplier1
valueTotal expense for that expense line20.38
class5 string options:
SUPER
SUPER2
SUPER3
FRINGE
'' {null} = Default
SUPER3


'ded_list' variables [0]

Field nameExplanationExample
noteDescription of the deductionSuper-Job C
rateDeduction rate9.500
multMultiplier1
valueTotal deduction for that deduction line20.38
class4 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","EmployeeID":"ABC123","pay_list":[{"note":"Basic Job A","date":"2021-12-20","LID":"856","ROID":"521","JID":"907","rate":"20.5","hours":"9","mult":"1","value":"184.50","class":"FALSE","STP":""},{"note":"Fixed extra","date":"2021-12-20", "LID":"856","ROID":"521","JID":"909","rate":"10","hours":"3","mult":"1","value":"30.00","class":"TRUE","STP":""},{"note":"Super Exclusive-Job C","date":"2021-12-20", "LID":"856","ROID":"521","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

{
  "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",
            "EmployeeID": "ABC123",
            "pay_list": [
              {
                "note": "Basic Job A",
                "date": "2021-12-20",
                "LID": "856",
                "ROID": "521",
                "JID": "907",
                "rate": "20.5",
                "hours": "9",
                "mult": "1",
                "value": "184.50",
                "class": "FALSE",
                "STP": ""
              },
              {
                "note": "Fixed extra",
                "date": "2021-12-20",
                "LID": "856",
                "ROID": "521",
                "JID": "909",
                "rate": "10",
                "hours": "3",
                "mult": "1",
                "value": "30.00",
                "class": "TRUE",
                "STP": ""
              },
              {
                "note": "Super Exclusive-Job C",
                "date": "2021-12-20",
                "LID": "856",
                "ROID": "521",
                "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"
              }
            ]
          }
        ]
      }
    ]
  }
}