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:
Variable name | Value - Minimum requirement |
mk_action | create_account |
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 32 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:
Variable name | Value - Minimum requirement |
mk_action | add_bank_details |
mk_data | {"bank_title":"Business ABC","bank_BSB":"063504","bank_account_no":"111222333"} |
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 |
Optional | ||||
bank_nickname | No | Nickname | Alphanumeric | Primary |
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 | 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 |
{ "success":"1", "authenticated":"1", "message":"Bank account added" }
If a bank account is already present with the same details, the response success will still be true.
{ "success":"1", "authenticated":"1", "message":"This bank account is already present" }
Failed response
{ "success":"0", "authenticated":"1", "message":"BSB not found" }