API Accounts

The account actions let an approved reseller set up Microkeeper accounts for their customers. create_account creates an account and returns its business key. The other actions set up the account's bank accounts, ABNs and pay cycles, and choose which payroll officers can see each pay cycle.

This guide covers how to:

1. Create and update an account.
2. Add a bank account.
3. Add and update ABNs.
4. Add and update pay cycles.
5. Choose who can see each pay cycle.
6. Get the ABNs and pay cycles.

Before you start, make your keys and test your connection: see Microkeeper API.

Become a reseller

Resellers bill their customers for Microkeeper and set up their accounts. To become one, contact Microkeeper: there's a vetting process, and Microkeeper turns on reseller access for your developer key. When you set up an account, your sign-up must link to Microkeeper's Terms of Use and Privacy Policy, with a box the customer ticks to agree.

Create and update an account with create_account

Send create_account with your developer key and your own account's business key. Microkeeper checks your developer key has reseller access.

Example

{
  "business_id": "cust-20419",
  "bus_name": "Harbour Lane Cafe Pty Ltd",
  "trading": "Harbour Lane Cafe",
  "abn": "51824753556",
  "email": "accounts@harbourlanecafe.com.au",
  "firstname": "Priya",
  "lastname": "Nair",
  "phoneno": "0355501234",
  "address": "12 Harbour Lane",
  "city": "Geelong",
  "state": "VIC",
  "postcode": "3220",
  "starting_day": "monday",
  "noemployees": 12,
  "active": 1
}

How accounts are matched

business_id is your ID for the customer. The first time you send it, an account is created. After that, sending it again updates that account, so a retry never makes a second account. Keep each customer's business_id unique and unchanging.

Fields

An update sets every field above except business_id, starting_day, noemployees, mobile, branch and accounting, which are set when the account is created. Send every field on each update, including active: a field you leave out goes back to its default, and an account sent without active is made active.

Response

{"success":"1","authenticated":"1","message":"Registration Successful","data":{"username":"harbour_lane_ca","mk_biz_key":"tt50SukqohfGwcwlyyxtPWOF390UXdBv","business_id":"cust-20419","update":0}}

Use the account's mk_biz_key, with your developer key, for every other action on that account. If a key is lost or exposed, the business revokes it and makes a new one in Settings: see Microkeeper API.

Errors

• This dev key is not set as a reseller: contact Microkeeper to become a reseller.
• A mandatory field is missing: business_id, abn, bus_name, email
• The ABN (12345678901) failed validation
• Email address invalid, Number of employees invalid
• Allow values for active at 0, 1, 2

Show the message to your customer so they can fix it. Several problems can be reported in one message.

Test your set-up

• Send the same business_id twice: the second response has the same username and update 1.
• Send a business name with symbols, such as O'Brien & Sons (Aust.) Pty Ltd, and check the JSON arrives intact. Some symbols are removed from the username.
• Call hello_world with the new account's key.

Add a bank account with add_bank_details

Add the business's bank account, for paying wages and super. The business still verifies its main bank account in Microkeeper before paying super.

{"bank_title":"HARBOUR LANE CAFE","bank_BSB":"062-000","bank_account_no":"12345678","bank_nickname":"Wages","bank_code":"CBA","bank_note":"Wages"}

A BSB and account number already in Microkeeper updates that bank account; otherwise it's added. On an update, optional fields you leave out go back to their defaults.

Response

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

BDID is the bank account's ID. Use it as the bank account for an ABN or pay cycle. update is 1 if an existing account was updated.

Errors

• bank_title missing or blank, bank_BSB missing, bank_account_no missing or blank, bank_nickname missing or blank
• BSB not found: check the BSB against the bank's details.
• Bank Nickname must be unique

Add and update ABNs with upsert_abn_v2

Each ABN pays one or more pay cycles, and reports its pay runs to the ATO through STP. Match ABNs by your own ID, abn_third_ID, or by Microkeeper's ABNID from get_abn_pay_cycle.

{"abn_third_ID":"cust-20419-abn-1","abn":"51824753556","abn_name":"Harbour Lane Cafe Pty Ltd","abn_trading":"Harbour Lane Cafe","abn_branch":"001","abn_address1":"12 Harbour Lane","abn_city":"Geelong","abn_state":"VIC","abn_postcode":"3220","abn_email":"accounts@harbourlanecafe.com.au","abn_phone":"0355501234","abn_accounting":"xero","abn_BDID":362}

Send every field on each update: fields you leave out go back to their defaults. An ABN's number is set when it's added. To pay from a different ABN, add it as a new ABN and move the pay cycles to it.

Response

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

The message is ABN added or ABN updated. Get the new ABN's ABNID from get_abn_pay_cycle, or keep matching by your abn_third_ID.

Errors

• abn missing, ABNID or abn_third_ID missing
• The ABN (51824753557) failed validation
• Bank Account not found: check the abn_BDID.

Add and update pay cycles with upsert_pay_cycle_v2

A pay cycle is a group of staff paid together, such as Weekly or Monthly, under one ABN. Match pay cycles by your own ID, pc_third_ID, or by Microkeeper's PCID. Add new pay cycles with a pc_third_ID.

{
  "abn_third_ID": "cust-20419-abn-1",
  "pc_third_ID": "cust-20419-weekly",
  "title": "Weekly",
  "wip": 1,
  "start_day": "monday",
  "arrears": 3,
  "BDID": 362,
  "access": 1,
  "access_euser_ary": ["priya_nair"],
  "euser_ary": ["noah_reid", "amelia_brown"],
  "hide": 0
}

Send every field on each update: arrears, the bank accounts, access and hide go back to 0 if you leave them out. Leave out the staff list if your software doesn't manage who's in the pay cycle. To move one employee to a pay cycle, send PCID_third_ID on the employee: see API Employee.

Response

{"data":{"access_user_list":["priya_nair"],"user_list":["noah_reid","amelia_brown"],"PCID":"8","update":0},"success":"1","authenticated":"1","message":"Pay Cycle successful"}

PCID is the pay cycle's ID, and update is 1 if it was updated. access_user_list and user_list list the officers and staff Microkeeper found: compare them with what you sent, as usernames it can't find are left out.

Errors

• ABNID or abn_third_ID missing, PCID or pc_third_ID missing, title missing, wip missing, start_day missing
• Allowed values for wip at 1, 2, 12, 24
• Allowed values for start_day are: monday, tuesday, wednesday, thursday, friday, saturday, sunday
• if access is set to 1, access_euser_ary, access_EID_list or access_EmployeeID_list must be present
• ABN not found: add the ABN first.
• Pay Cycle Title already present
• Wage Bank Account not found, Super Bank Account not found

Choose who can see each pay cycle with upsert_access_user_pay_cycle

Set the pay cycles each payroll officer can see. Send each officer with their full list: it replaces what they had. Officers you don't send are left as they are.

{
  "access_euser_ary": {
    "priya_nair": { "third_ID": ["cust-20419-weekly", "cust-20419-monthly"] },
    "sam_lee": { "PCID": ["8"] },
    "old_manager": "revoke"
  }
}

• Key the officers by username in access_euser_ary, by EID in access_EID_list, or by EmployeeID in access_EmployeeID_list.
• List pay cycles by your third_ID or by PCID.
• Send "revoke" to remove an officer from every pay cycle.
• Each pay cycle you grant is set to show only to its listed officers.

Every officer must be in Microkeeper: if one isn't found, nothing changes.

Response

{"success":"1","authenticated":"1","message":"Pay Cycle User Access Successful"}

Errors

• Either access_euser_ary, access_EID_list or access_EmployeeID_list must be present
• Employee access count does not match: an officer isn't in Microkeeper. Check each username.
• Pay Cycle third_ID (cust-20419-weekly) not found, Pay Cycle PCID (8) not found

Get the ABNs and pay cycles with get_abn_pay_cycle

Send {}. Every ABN is returned, with its pay cycles:

{
  "success": "1",
  "authenticated": "1",
  "message": "ABN and Pay Cycle config",
  "data": {
    "abn_ary": [
      {
        "ABNID": 194,
        "third_ID": "cust-20419-abn-1",
        "ABN": "51824753556",
        "abn_name": "Harbour Lane Cafe Pty Ltd",
        "abn_trading": "Harbour Lane Cafe",
        "abn_branch": "001",
        "abn_address1": "12 Harbour Lane",
        "abn_address2": "",
        "abn_city": "Geelong",
        "abn_state": "VIC",
        "abn_postcode": "3220",
        "abn_country": "Australia",
        "BDID": 362,
        "abn_email": "accounts@harbourlanecafe.com.au",
        "abn_phone": "0355501234",
        "abn_accounting": "xero",
        "payg_aba_ref": "",
        "agent_ABN": "0",
        "agent_is_TAN": 0,
        "agent_number": "0",
        "hide": 0,
        "default_super_fund": { "SFID": 8, "USI": "STA0100AU" },
        "pay_cycle_ary": [
          {
            "PCID": 4192,
            "third_ID": "cust-20419-weekly",
            "title": "Weekly",
            "wip": 1,
            "start_day": "monday",
            "arrears": 3,
            "ABNID": 194,
            "BDID": 362,
            "super_BDID": 0,
            "access": 1,
            "GID": 59462,
            "hide": 0,
            "access_euser_ary": ["priya_nair"]
          }
        ]
      }
    ]
  }
}

The fields match the ones you send, plus:

• default_super_fund: the ABN's default super fund, or [] if none is set.
• GID: the Group of staff in the pay cycle. Use it to find an employee's pay cycle from their groups in get_employees.
• access_euser_ary: the payroll officers who can see the pay cycle.

Errors

• No ABN found, No Pay Cycles found: the account has no ABNs or pay cycles yet.