Creating Microkeeper Account via API

This guide will explain how to create a Microkeeper account via the API.

This is only for Resellers of Microkeeper that have been whitelisted.

Complete a Hello World API call

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

Creating and updating a Microkeeper accounts via API

Reseller Access

Step 1

In this scenario the reselling is doing the billing of Microkeeper and they are provisioning the Microkeeper account.

The reseller must include links to our Terms of use and Privacy Policy as part of the account provisioning process, with a checkbox sign process included.

They will need to store the returned mk_biz_key if they wish to utilise other API endpoints.

There is a vetting process to becoming a reseller.

Required Variables

Step 2

Set the mk_action variable and mk_data variable:

mk_action create_account

HTTP Method POST

mk_data

{"business_id":"abc123","bus_name":"Business name Pty Ltd","email":"test@gmail.com","abn":"95149280320"}

Since there is no Microkeeper account yet, the mk_biz_key must be set to that of the developer.

The API will check that the integrator has reseller rights with Microkeeper, if not an error will be returned.

mk_data Payload

Step 3

API Response

Step 4

If successful Microkeeper will response with the following fields in the data object:

Example

JSON response:

{"success":1,"authenticated":1,"message":"Registration Successful","data":{"username":"abc_engineering","mk_biz_key":"tt50SukqohfGwcwlyyxtPWOF390UXdBv","business_id":"abc123","update":1}}

Same response as an array:

Array
(
    [success] => 1
    [authenticated] => 1
    [message] => Registration Successful
    [data] => Array
        (
            [username] => abc_engineering
            [mk_biz_key] => tt50SukqohfGwcwlyyxtPWOF390UXdBv
            [business_id] => abc123
            [update] => 1
        )
)

Things to Test

Step 5

1. Make sure if the same business_id is passed multiples times only one account is created.
   The username returned should always be the same and update should be set to 0 on the first API call and 1 for each API call after that.
   
   
2. If success is set to 0 then message is an error message and best practice would be to return this to the user.
   Example "ABN is not valid"
   
   
3. Test a business name with special characters to make sure they are encoded correctly and not breaking the JSON.
   Microkeeper will sanitise this data, so it's likely some characters will be removed, but still pass validation.
   Example ABC ~!@#$%^&*()_+`1{{}|[]\:",./?>< PTY LTD
   
   
4. If compromised a mk_biz_key will need to be replaced, so it should be possible to run the provisioning process again.

Adding a Bank account Via API

When provisioning an account you can add the business bank account.

This step is optional, bank accounts can also be managed in Microkeeper.

The account holder will still need to go through a verification process for the primary bank account before paying super.

Business Logic

1. The BSB and Account Number are used to uniquely ID an account, if found it will be updated if not found it will be inserted.
2. The Bank Account Nickname must be unique.
3. The BSB is validated against an official list, more details below

Required Variables

Step 1

Set the mk_action variable and mk_data variable:

mk_action add_bank_details

HTTP Method POST

mk_data

{"bank_title":"Account 44","bank_BSB":"63504","bank_account_no":"4444444","bank_nickname":"ANZ","GID":"@all","bank_code":"ANZ","bank_APCA":"0","bank_note":"Wages"}

mk_data Payload

Step 3

List of all BSBs

http://bsb.apca.com.au/

This list of BSB is maintained, it's recommended to update your application on a periodic basis.

Example monthly for high volume or annually for low volume.

bank_code list

ANZ has some inconsistency between ANZ products, so workarounds need to be in place when generating the ABA file, AN2 and AN3 are converted to ANZ when the ABA file is created

Responses

If bank account is not present it will be added:

{"success":"1","authenticated":"1","message":"Bank Details successful","data":{"BDID":"362","update":0}}

If a bank account is already present it will be updated:

{"success":"1","authenticated":"1","message":"Bank Details successful","data":{"BDID":"362","update":1}}

Failed response

{ "success":"0", "authenticated":"1", "message":"BSB not found" }

BDID = Bank Details ID

This can be used to assign a bank account when adding or updating an ABN or Pay Cycle.

Adding and updating an ABN via API

The ABN is used as a Primary key on a per account basis, if a record is found this will be updated if not found a new record will be inserted.

mk_action upsert_abn

HTTP Method POST

mk_data

{ "abn": "95149280320", "abn_name": "Business Pty Ltd", "abn_trading": "Trading Name", "abn_branch": "001", "abn_postcode": "2000", "abn_country": "Australia", "abn_email": "contact@business.com", "abn_phone": "0400111222", "abn_accounting": "xero", "hide": 0 } 

Response Payload 

{"success":"1","authenticated":"1","message":"ABN added"}

Same response as an array

Array
(
    [success] => 1
    [authenticated] => 1
    [message] => ABN added
)

Logging

An API log entry is created for both "ABN updated" and "ABN added" events.

Update or insert a Pay Cycle via API

Action upsert_pay_cycle

HTTP Method POST

mk_data

{ "third_ID":"aaa111", "abn": "12345678901", "title":"Monthly", "wip": 12, "start_day": "monday", "arrears": 1, "access": 1, "hide": 0, "access_euser_ary": ["user1", "user2"], "euser_ary": ["user1", "user3"] } 

Business Logic

• ABN Validation: The provided ABN must be valid and must already be present before a Pay Cycle can be added.
• WIP Validation: The value for wip must be one of the allowed values (1, 2, 12, 24).
• Start Day Validation: The start day must be a valid day of the week (for WIP 1 and 2).
• Access Control: If access is set to 1, the request must include either: access_euser_ary, access_EID_list, or access_EmployeeID_list.
  This also means the third party system is the source of truth, if there are existing present they will be unallocated.
  If access is set to 0, all users with access to Payroll will have access to the Pay Cycle.
• Staff User List: If the third party system is the source of truth supply the list of staff by including either: euser_ary, EID_list, or EmployeeID_list.
• Unique Title: The title of the Pay Cycle must be unique.

Responses Payload

user_list 

• The users that were assigned to this Pay Cycle 
• This is Microkeepers employee username
• If the username list supplied can not be found they will not be added but there will be no error message

access_user_list

• The users that were assigned to this Pay Cycle for Access Control
• This is Microkeepers employee username
• If the username list supplied can not be found they will not be added but there will be no error message

{"data":{"access_user_list":["john_smith","alice_long"],"user_list":["john_smith","alice_long"],"PCID":"8","update":1},"success":"1","authenticated":"1","message":"Pay Cycle successful"} 

Same response as an array

Array
(
    [success] => 1
    [authenticated] => 1
    [message] => Pay Cycle successful
    [data] => Array
    (
        [access_user_list] => Array
        (
            [0] => john_smith
            [1] => alice_long
        )
        [user_list] => Array
        (
            [0] => john_smith
            [1] => alice_long
        )
        [PCID] => 8
        [update] => 1
    )
)

Logging

An API log entry is created for both "ABN updated" and "ABN added" events.