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.

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.

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

'config' variables

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

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

'ded_list' variables

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 to make a comparison.

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 or a List of Payruns

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.

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

{"payrun_id":[{"year":2018,"run_id":48},{"year":2018,"run_id":49}],"EmployeeID":[111]}

{"start_date":"2018-07-01","end_date":"2019-06-30", "eusername":["john_smith"],"EmployeeID":[111,222,333],"EID":[3,4,6]}

Use Case

get_payroll - Includes a full list of payroll data, this can be used for: full reporting, analysis requirement, supplying a payslip to an employee

get_payrun_list - Includes just the payrun, this can be used for: Providing a list of payruns to an employee, it includes less data so will load faster

Step 2

List of available fields

Below is a list of variables that can be used to get payroll data, either By Date, or By Payrun ID must be present

It is possible to further filter by searching via a list eusername, EID or EmployeeID.

Step 3

Response

The response will include a list of Payruns and Super funds related to the users.

Each Payrun will include a list of Payslips. 

'super_fund_detail' object

This object has a key of the ID of the super_fund.

Example

"482":{"name":"REST","ABN":"62653671394","USI":"RES0103AU","open":"1"}

482 is our ID for the fund.

'super_fund_detail' variables

USI will not be set for SMSF, thus ABN should be used if USI is blank.

'runs' object [0]

'run_data' variables

'payslips' variables [0]

'pay_list' variables [0]

'exp_list' variables [0]

'ded_list' variables [0]

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":{"pay_cycle_title":"Casuals","abn":"95149280320","abn_name":"ABN Engineering PTY LTD","abn_trading":"ABN Engineering","PCID":"0","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","annual_net":"2216.08","annual_tax":"2.00","EID":"3","EmployeeID":"ABC123","super_fund":"482","super_no":"987654321","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"}]}]}]},"super_fund_detail":{"482":{"name":"REST","ABN":"62653671394","USI":"RES0103AU","open":"1"}}}

Same Example Readable

{
  "success": "1",
  "authenticated": "1",
  "message": "Payrun data",
  "data": {
    "runs": [
      {
        "run_data": {
          "pay_cycle_title": "Casuals",
          "abn": "95149280320",
          "abn_name": "ABN Engineering PTY LTD",
          "abn_trading": "ABN Engineering",
          "PCID": "0",
          "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",
            "annual_net":"2216.08",
            "annual_tax":"2.00",
            "EID": "3",
            "EmployeeID": "ABC123",
            "super_fund":"482",
            "super_no": "987654321",
            "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"
              }
            ]
          }
        ]
      }
    ]
  },
  "super_fund_detail": {
    "482": {
      "name":"REST",
      "ABN":"62653671394",
      "USI":"RES0103AU",
      "open":"1"
    }
  }
}