This guide will explain how to create a Microkeeper account via the API.
This is only for Resellers of Microkeeper that have been whitelisted.
Before starting this tutorial make sure you have completed the Hello World tutorial.
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.
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.
Step 3
Field Name | Required | Description | Format | Example | Notes |
business_id | Yes | This is your ID, it must be unique to each account in your database | Alphanumeric and some special character up to 64 characters | wjf2Ns4kj6e78a9s90dhfkhAks | If not present in Microkeeper this is used to create the account If present in Microkeeper this is used to update the account |
bus_name | Yes | Business Name | Alphanumeric | ABC Engineering Pty Ltd | This is used to generate the username |
Yes | Email Address | Email format | test@gmail.com | Email address must be verified before passing | |
abn | Yes | Australian Business Number | ABN validation | 51 824 753 556 | If ABN is invalid API call will fail and error message returned |
phoneno | No | For all non mobile numbers | Numeric | 1800 000 111 | |
mobile | No | Mobile phone numbers | Numeric starting with 04 | 0411 222 333 | |
noemployees | No | Number of employees | Integer | 10 | Helpful for our sales and support staff to recommend modules |
branch | No | STP Business branch code | Int with 2 leading 0s | 001 | |
active | No | Make the account active (1) | 0 = Inactive 1 = Active 2 = Suspended | 1 | The first time the account is create this value is set to 0 once the user logs in for the first time it changes to 1 This field can be used to suspended an account due to: billing issues or inactivity |
super_freq | No | How often the Business processes super | pay = Each Payrun mth = Monthly qtr = Quarterly | qtr | |
accounting | No | Possible options | max 4 char lowercase | xero | If unknown leave blank or exclude If known but not listed as an option, you can still pass through in the allowed format |
starting_day | No | Starting day of the payrun week | lowercase day of the week monday,tuesday,etc | monday | Used to create the primary pay cycle Eg if monday pay cycles will be monday to sunday No impact on monthly pay cycles, if unknown set to monday |
trading | No | Trading name if different from Business Name | Alphanumeric | ABC Engineering | |
firstname | No | Primary Contact of Business | String | John | |
lastname | No | Primary Contact of Business | String | Smith | |
address | No | Address of HQ - Line 1 | Alphanumeric | Unit 10 | |
address2 | No | Address of HQ - Line 2 | Alphanumeric | 1 Main St | |
city | No | Address suburb | Alphanumeric | Belmont | |
state | No | Australian State | VIC, ACT, NSW, NT, QLD, SA, TAS, WA, OTH | VIC | If outside of Australia set the value to OTH |
postcode | No | Australia Post Code | Int to 4 chars | 3216 | |
country | No | Country | 2 char country code, ISO format | AU | https://www.iban.com/country-codes |
Step 4
If successful Microkeeper will response with the following fields in the data object:
Field Name | Description | Format | Example |
username | Microkeeper will generate this username from the bus_name you provide, it will be unique for all Microkeeper accounts. We use this internally to help with support. | lowercase and underscore | abc_engineering |
mk_biz_key | This is used to access the data within the account going forwards | 32 digit key | tt50SukqohfGwcwlyyxtPWOF390UXdBv |
business_id | The business_id that was passed in, this should be compared to the original ID to make sure they match If they do not match and the same business_id is used again, we could end up with duplicates. | Alphanumeric and some special character up to 32 characters | abc123 |
update | 0 = New account created 1 = Existing account updated | Boolean | 1 |
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
)
)
Step 5
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.
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"}
Step 3
Field Name | Required | Description | Format, Options | Example |
bank_title | Yes | Bank account Title | Alphanumeric, some special characters will be removed if incompatible with the ABA file standards | Business ABC |
bank_BSB | Yes | Bank account BSB | xxx-xxx or xxxxxx Leading 0s are adding if missing Must be a valid BSB number | 63504 or 063504 or 063-504 |
bank_account_no | Yes | Bank account Number | Numeric | 12345679 |
bank_nickname | Yes | Nickname | Alphanumeric Must be unique | Primary |
Optional | ||||
GID | No | Group ID | @ID Default @all We do not recommend including this | @all |
bank_code | No | Code from the Bank | 3 char upper case Recommend else ABA file will fail Full list below | ANZ |
bank_APCA | No | Number provided by the bank | 6 digit number, default to 000000 as not required by many banks | 000000 |
bank_note | No | Note that will appear on the bank statement when paying staff | String, default is "Wages" 12 Char max | Wages |
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.
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
bank_code | Bank Name |
AMP | AMP Bank |
ANZ | ANZ - Business |
AN2 | ANZ - Transactive |
AN3 | ANZ - Transactive Global |
ARA | Arab Bank Australia |
MPB | Auswide Bank |
BAU | Bank Australia |
BAL | Bank of America |
BOC | Bank of China Australia |
BCY | Bank of Cyprus Australia |
BOM | Bank of Melbourne |
BOQ | Bank of Queensland |
BSA | BankSA |
BWA | BankWest |
BBL | Bendigo Bank |
BYB | Beyond Bank Australia |
CTI | Citibank |
CBA | Commonwealth Bank of Australia |
CUA | Credit Union Aust Ltd |
SGE | G and C Mutual Bank |
GBS | Greater Building Society |
HBA | HSBC Bank Australia |
IMB | Illawarra Mutual Building Society |
CUS | Indue Ltd |
ING | ING Bank |
MBL | Macquarie Bank |
MEB | Members Equity Bank |
CRU | MyState Bank |
NAB | National Australia Bank |
PIB | Rabobank Australia Limited |
QTM | RACQ Bank |
RBA | Reserve Bank of Australia |
STG | St George Bank |
SCU | Summerland Credit Union |
MET | Suncorp-Metway |
MSL | Tyro Payments Limited |
UOB | United Overseas Bank |
WB2 | Westpac - Balance Line |
WBC | Westpac - No Balance Line |
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.
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 }
Field Name | Required | Use for | Description | Format | Example | Default |
---|---|---|---|---|---|---|
abn | Yes | Super / STP | The Australian Business Number (ABN) Validation will be performed on this field This field is also the primary key | ABN | 95149280320 | NA |
abn_name | No | Super / STP | The name associated with the ABN | 50 Char String | Business Pty Ltd | |
abn_trading | No | NA | The trading name associated with the ABN | 50 Char String | Trading Name | |
abn_branch | No | STP | The branch number of the ABN | 3 Char String | 001 | 001 |
abn_postcode | No | STP | The post code of the ABN | Postcode | 2000 | |
abn_country | No | STP | The country associated with the ABN | String | Australia | Australia |
abn_email | No | Super / STP | The email associated with the ABN. | String | contact@business.com | |
abn_phone | No | Super | The phone number associated with the ABN. | String | 0400111222 | |
abn_accounting | No | Reporting | The accounting software used by the business for this ABN | Possible options: xero myob comp (Companion Software) ms (Microsoft Business Central) qb (Quickbooks) reck (Reckon) excel (Spreadsheet) false (Other) - {String false} | xero | |
abn_BDID | No | Super | The Bank Account ID used to process super | Key ID of Microkeeper | 12345 | 0 |
hide | No | NA | A flag to hide or show the ABN record | Boolean 0 = not hidden 1 = hidden | 0 | 0 |
{"success":"1","authenticated":"1","message":"ABN added"}
Same response as an array
Array
(
[success] => 1
[authenticated] => 1
[message] => ABN added
)
An API log entry is created for both "ABN updated" and "ABN added" events.
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
Field | Type | Description | Char Length | Required | Default Value | Example Value |
---|---|---|---|---|---|---|
Primary Key Options: | ||||||
PCID | int | Pay Cycle ID | 11 | Yes, or third_ID | 1001 | |
third_ID | string | External third-party ID | 32 | Yes, or PCID | aaa111 | |
Fields: | ||||||
abn | string | Australian Business Number (ABN), validated. | 11 | Yes | 12345678901 | |
title | string | Title of the pay cycle. | 24 | Yes | Monthly | |
wip | int | Week In Period, Allowed: 1 = Weekly 2 = Fortnightly 12 = Monthly 24 = Semi-Monthly | 2 | Yes | 12 | |
start_day | string | Day the cycle starts. Onay affect weekly or fortnightly | 9 | Yes | monday | |
arrears | int | Indicates if arrears apply Range: -14 to +20 | 1 | No | 0 | 1 |
BDID | int | The Bank Account ID used to process staff wages Key ID of Microkeeper | 11 | No | 0 | 12345 |
access | int | Restricts access 0 = All payroll officers can access 1 = Access required, requires Access List | Boolean | No | 0 | 1 |
hide | int | Hides the pay cycle (0 or 1). | Boolean | No | 0 | 1 |
Access List Options: | ||||||
access_euser_ary | array | Array of usernames for access control. | No | ["user1", "user2"] | ||
access_EID_list | array | Array of employee IDs for access control. | No | [1001,1002] | ||
access_EmployeeID_list | array | Array of Employee IDs for access control, this is the third party system ID | No | [1,2,3] | ||
User Staff List Options: | ||||||
euser_ary | array | Array of staff IDs to add to the pay cycle. | No | ["user1", "user2"] | ||
EID_list | array | Array of employee IDs to add to the pay cycle. | No | [1001,2001] | ||
EmployeeID_list | array | Array of Employee IDs to add to the pay cycle, this is the third party system ID | No | [1,2,3] |
user_list
access_user_list
{"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
)
)
An API log entry is created for both "ABN updated" and "ABN added" events.