Skip to content
Beautiful accounting software

Developer

See all pages

Paycycle API

Transition to the Xero API

The current Paycycle API is separate to the main Xero API – please see the following details on it’s status.

Architecture

The Paycycle API has been developed with Windows Communication Foundation (WCF) Services in Microsoft .NET 4. Communication with these services is made via HTTPS using XML.

Security

Aside from transport security provided by SSL, Paycycle has implemented authentication and authorisation for calls to the API. For an API call to be accepted, three conditions must be met.

API key – This is a GUID created by Paycycle and supplied to our partner applications, and is used to identify calls from partner applications to Paycycle.

IP Filtering – Partner applications need to supply Paycycle with a range of IP addresses. Requests from partner applications to the Paycycle API using the API Client key must be made from an IP address in the range provided, or the call will not be accepted.

Customer Authorisation key – This is a GUID created by Paycycle and supplied to partner applications, representing a customer of both Paycycle and the partner application. It is used to authorise the customer’s access to the Paycycle functionality through the partner application. Initially this key will be set up by a request to Paycycle Support.

Each call to the API requires the API Client key and the Customer Authorisation Key. Paycycle logs all calls made to the API regardless of whether the call succeeds or not.

Services and Methods

Paycycle provides three services for use by partner applications, the Employee service, the PayRun service and the Timesheet service. Schemas for request and response xml can be provided. The descriptions of service methods below display examples of request and response xml and a description of values where pertinent. The response xml returned by every service method will contain a Status and Error Description which will be OK and nil respectively if the method succeeds. The following is a list of Statuses and Error Descriptions that can be returned by all service methods.

1.) Status = ERROR
Error Description = INVALID CLIENT KEY.
Occurs when the API Client Key passed cannot be found.

2.) Status = ERROR
Error Description = INVALID IP ADDRESS.
Occurs when the call is made from an IP Address outside the range provided to Paycycle by the partner application.

3.) Status = ERROR
Error Description = ACCESS DENIED.
Occurs when the Authorisation Key is not found or not associated with the API client key.

4.) Status = ERROR
Error Description = An exception occurred. Please contact Paycycle support.
Occurs when there is an exception in processing the request.

More details about each Payroll endpoint are listed below.

GetAllEmployees
GetEmployee
GetEmployeeDetailed
AddEmployee
UpdateEmployee
SetEmployeeBankAccount
UploadTimeSheet

GetAllEmployees

URL https://payroll.xero.com/API/Employee/Employee.svc/GetAllEmployees
Description This method retrieves all employees associate with the customer making the request

Response element for GetAllEmployees

EmployeeID The internal identifier for the employee
HasOrdinaryEarningsRate indicates whether the employee has an ordinary earnings rate in Paycycle

Request:

<GetAllEmployeesRequest xmlns="http://api.paycycle.com.au/v1.0">
        <ApiKey>00000000-0000-0000-0000-000000000000</ApiKey>
        <AuthorisationKey>00000000-0000-0000-0000-000000000000</AuthorisationKey>
    </GetAllEmployeesRequest>

Response:

<GetAllEmployeesResponse xmlns="http://api.paycycle.com.au/v1.0">
        <Status>OK</Status>
        <ErrorDescription></ErrorDescription>
        <Employees>
            <Employee>
                <EmployeeID>2022</EmployeeID>
                <FirstGivenName>John</FirstGivenName>
                <HasOrdinaryEarningsRate>true</HasOrdinaryEarningsRate>
                <Surname>Smith</Surname>
            </Employee>
            <Employee>
                <EmployeeID>2062</EmployeeID>
                <FirstGivenName>Jane</FirstGivenName>
                <HasOrdinaryEarningsRate>false</HasOrdinaryEarningsRate>
                <Surname>Johnson</Surname>
            </Employee>
        </Employees>
    </GetAllEmployeesResponse>

GetEmployee

URL https://payroll.xero.com/API/Employee/Employee.svc/GetEmployee
Description This method retrieves the specified employee for the customer making the request.

Response element for GetEmployee

EmployeeID The internal identifier for the employee
HasOrdinaryEarningsRate indicates whether the employee has an ordinary earnings rate in Paycycle

Request:

<GetEmployeeRequest xmlns="http://api.paycycle.com.au/v1.0">
        <ApiKey>00000000-0000-0000-0000-000000000000</ApiKey>
        <AuthorisationKey>00000000-0000-0000-0000-000000000000</AuthorisationKey>
        <EmployeeID>2022</EmployeeID>
    </GetEmployeeRequest>

Response:

<GetEmployeeResponse xmlns="http://api.paycycle.com.au/v1.0">
        <Status>OK</Status>
        <ErrorDescription></ErrorDescription>
        <Employee>
            <EmployeeID>2022</EmployeeID>
            <FirstGivenName>John</FirstGivenName>
            <HasOrdinaryEarningsRate>true</HasOrdinaryEarningsRate>
            <Surname>Smith</Surname>
        </Employee>
    </GetEmployeeResponse>

The response is a single employee or nil if no employee is found for the customer making the request.

GetEmployeeDetailed

URL https://payroll.xero.com/API/Employee/Employee.svc/GetEmployeeDetailed
Description This method retrieves the specified employee for the customer making the request

Request:

<GetEmployeeDetailedRequest xmlns="http://api.paycycle.com.au/v1.0">
        <ApiKey>00000000-0000-0000-0000-000000000000</ApiKey>
        <AuthorisationKey>00000000-0000-0000-0000-000000000000</AuthorisationKey>
        <EmployeeID>2022</EmployeeID>
    </GetEmployeeDetailedRequest>

Response:

<GetEmployeeDetailedResponse xmlns="http://api.paycycle.com.au/v1.0">
        <Status>OK</Status>
        <ErrorDescription></ErrorDescription>
        <Employee>
            <EmployeeID>2022</EmployeeID>
            <PayerEmployeeNumber>5214520</PayerEmployeeNumber>
            <Title>Mr</Title>
            <FirstGivenName>John</FirstGivenName>
            <Surname>Smith</Surname>
            <OtherGivenNames>Frederick</OtherGivenNames>
            <DateOfBirth>1908-11-11T00:00:00</DateOfBirth>
            <Gender>M</Gender>
            <HomeAddressLines>1 John St</HomeAddressLines>
            <HomeSuburb>Smithville</HomeSuburb>
            <HomeStateAbbreviation>NSW</HomeStateAbbreviation>
            <HomePostCode>2121</HomePostCode>
            <HomeCountryCode>AU</HomeCountryCode>
            <Telephone>04112345678</Telephone>
            <Mobile>04112345678</Mobile>
            <Email>john@hotmail.com</Email>
            <TwitterUserName>@john</TwitterUserName>
            <StartDate>1956-02-01T00:00:00</StartDate>
            <EndDate>2003-09-15T00:00:00</EndDate>
            <Occupation>Engineer</Occupation>
            <Classification>Level 3.2</Classification>
        </Employee>
    </GetEmployeeDetailedResponse>

AddEmployee

URL https://payroll.xero.com/API/Employee/Employee.svc/AddEmployee
Description This method allows an employee to be added to Paycycle

Request:

<AddEmployeeRequest xmlns="http://api.paycycle.com.au/v1.0">
        <ApiKey>00000000-0000-0000-0000-000000000000</ApiKey>
        <AuthorisationKey>00000000-0000-0000-0000-000000000000</AuthorisationKey>
        <Employee>
            <PayerEmployeeNumber>5214520</PayerEmployeeNumber>
            <Title>Mr</Title>
            <FirstGivenName>John</FirstGivenName>
            <Surname>Smith</Surname>
            <OtherGivenNames>Frederick</OtherGivenNames>
            <DateOfBirth>1908-11-11T00:00:00</DateOfBirth>
            <Gender>M</Gender>
            <HomeAddressLines>1 John St</HomeAddressLines>
            <HomeSuburb>Smithville</HomeSuburb>
            <HomeStateAbbreviation>NSW</HomeStateAbbreviation>
            <HomePostCode>2121</HomePostCode>
            <HomeCountryCode>AU</HomeCountryCode>
            <Telephone>04112345678</Telephone>
            <Mobile>04112345678</Mobile>
            <Email>john@hotmail.com</Email>
            <TwitterUserName>@john</TwitterUserName>
            <StartDate>1956-02-01T00:00:00</StartDate>
            <EndDate>2003-09-15T00:00:00</EndDate>
            <Occupation>Engineer</Occupation>
            <Classification>Level 3.2</Classification>
        </Employee>
    </AddEmployeeRequest>

Response:

<AddEmployeeResponse xmlns="http://api.paycycle.com.au/v1.0">
        <Status>OK</Status>
        <ErrorDescription></ErrorDescription>
        <EmployeeID>2022</EmployeeID>
    </AddEmployeeResponse>

UpdateEmployee

URL https://payroll.xero.com/API/Employee/Employee.svc/UpdateEmployee
Description This method allows an employees details to be updated.

Request:

<UpdateEmployeeRequest xmlns="http://api.paycycle.com.au/v1.0">
        <ApiKey>00000000-0000-0000-0000-000000000000</ApiKey>
        <AuthorisationKey>00000000-0000-0000-0000-000000000000</AuthorisationKey>
        <Employee>
            <EmployeeID>2022</EmployeeID>
            <PayerEmployeeNumber>5214520</PayerEmployeeNumber>
            <Title>Mr</Title>
            <FirstGivenName>John</FirstGivenName>
            <Surname>Smith</Surname>
            <OtherGivenNames>Frederick</OtherGivenNames>
            <DateOfBirth>1908-11-11T00:00:00</DateOfBirth>
            <Gender>M</Gender>
            <HomeAddressLines>1 John St</HomeAddressLines>
            <HomeSuburb>Smithville</HomeSuburb>
            <HomeStateAbbreviation>NSW</HomeStateAbbreviation>
            <HomePostCode>2121</HomePostCode>
            <HomeCountryCode>AU</HomeCountryCode>
            <Telephone>04112345678</Telephone>
            <Mobile>04112345678</Mobile>
            <Email>john@hotmail.com</Email>
            <TwitterUserName>@john</TwitterUserName>
            <StartDate>1956-02-01T00:00:00</StartDate>
            <EndDate>2003-09-15T00:00:00</EndDate>
            <Occupation>Engineer</Occupation>
            <Classification>Level 3.2</Classification>
        </Employee>
    </UpdateEmployeeRequest>

Response:

<UpdateEmployeeResponse xmlns="http://api.paycycle.com.au/v1.0">
        <Status>OK</Status>
        <ErrorDescription></ErrorDescription>
    </UpdateEmployeeResponse>

SetEmployeeBankAccount

URL https://payroll.xero.com/API/Employee/Employee.svc/SetEmployeeBankAccount
Description This method allows the employee’s bank account details to be set.

Request:

<SetEmployeeBankAccountRequest xmlns="http://api.paycycle.com.au/v1.0">
        <ApiKey>00000000-0000-0000-0000-000000000000</ApiKey>
        <AuthorisationKey>00000000-0000-0000-0000-000000000000</AuthorisationKey>
        <BankAccount>
            <EmployeeID>2022</EmployeeID>
            <ReferenceText>Salary</ReferenceText>
            <BSB>123123</BSB>
            <AccountNumber>12345678</AccountNumber>
            <AccountName>Mr J. Smith</AccountName>
        </BankAccount>
    </SetEmployeeBankAccountRequest>

Response:

<SetEmployeeBankAccountResponse xmlns="http://api.paycycle.com.au/v1.0">
        <Status>OK</Status>
        <ErrorDescription></ErrorDescription>
    </SetEmployeeBankAccountResponse>

Only a single bank account can be set through the API. Existing bank account details are overridden.

GetCurrentPayRunStatus

URL https://payroll.xero.com/API/PayRun/PayRun.svc/GetCurrentPayRunStatus
Description This method retrieves details of the current unposted pay run for the customer making the request

Request:

<GetCurrentPayRunStatusRequest xmlns="http://api.paycycle.com.au/v1.0">
        <ApiKey>00000000-0000-0000-0000-000000000000</ApiKey>
        <AuthorisationKey>00000000-0000-0000-0000-000000000000</AuthorisationKey>
    </GetCurrentPayRunStatusRequest>

Response:

<GetCurrentPayRunStatusResponse xmlns="http://api.paycycle.com.au/v1.0">
        <Status>OK</Status>
        <ErrorDescription></ErrorDescription>
        <PayRun>
            <PayRunID>257412</PayRunID>
            <StartDate>2011-04-01T00:00:00</StartDate>
            <EndDate>2011-04-30T00:00:00</EndDate>
            <Employees>
                <Employee>
                    <EmployeeID>2022</EmployeeID>
                    <FirstGivenName>John</FirstGivenName>
                    <HasOrdinaryEarningsRate>true</HasOrdinaryEarningsRate>
                    <Surname>Smith</Surname>
                </Employee>
                <Employee>
                    <EmployeeID>2062</EmployeeID>
                    <FirstGivenName>Jane</FirstGivenName>
                    <HasOrdinaryEarningsRate>false</HasOrdinaryEarningsRate>
                    <Surname>Johnson</Surname>
                </Employee>
            </Employees>
        </PayRun>
    </GetCurrentPayRunStatusResponse>

The pay run returned consists of the start and end dates for the pay run, and a list of employees. Employee ID is the internal identifier for the employee. HasOrdinaryEarningsRate indicates whether the employee has an ordinary earnings rate in Paycycle. The service method SetEarningsNumberOfUnits will not work for an employee unless they have an ordinary earnings rate.

SetEarningsNumberOfUnits

URL https://payroll.xero.com/API/PayRun/PayRun.svc/SetEarningsNumberOfUnits
Description This method allows the number of units for the currently active pay run to be set.

Request:

<SetEarningsNumberOfUnitsRequest xmlns="http://api.paycycle.com.au/v1.0">
        <ApiKey>00000000-0000-0000-0000-000000000000</ApiKey>
        <AuthorisationKey>00000000-0000-0000-0000-000000000000</AuthorisationKey>
        <EmployeesUnits>
            <EmployeeUnits>
                <EmployeeID>7403</EmployeeID>
                <StartDate>2011-04-06T00:00:00</StartDate>
                <EndDate>2011-04-12T00:00:00</EndDate>
                <NumberOfUnits>150</NumberOfUnits>
            </EmployeeUnits>
            <EmployeeUnits>
                <EmployeeID>21403</EmployeeID>
                <StartDate>2011-04-06T00:00:00</StartDate>
                <EndDate>2011-04-12T00:00:00</EndDate>
                <NumberOfUnits>33.5</NumberOfUnits>
                <RatePerUnit>21.2545</RatePerUnit>
            </EmployeeUnits>
        </EmployeesUnits>
    </SetEarningsNumberOfUnitsRequest>

Response:

<SetEarningsNumberOfUnitsResponse xmlns="http://api.paycycle.com.au/v1.0">
        <Status>OK</Status>
        <ErrorDescription></ErrorDescription>
    </SetEarningsNumberOfUnitsResponse>

Note that the RatePerUnit is optional. If not specified, the employees ordinary earnings rate will be used.

SetReimbursements

URL https://payroll.xero.com/API/PayRun/PayRun.svc/SetReimbursements
Description This method allows reimbursements to be added to the currently active pay run

Request:

<SetReimbursementsRequest xmlns="http://api.paycycle.com.au/v1.0">
        <ApiKey>00000000-0000-0000-0000-000000000000</ApiKey>
        <AuthorisationKey>00000000-0000-0000-0000-000000000000</AuthorisationKey>
        <Reimbursements>
            <Reimbursement>
                <EmployeeID>21403</EmployeeID>
                <Name>Car Expenses</Name>
                <Description>Petrol</Description>
                <RatePerUnit>75.00</RatePerUnit>
            </Reimbursement>
            <Reimbursement>
                <EmployeeID>21403</EmployeeID>
                <Name>Car Expenses</Name>
                <Description>Car Cleaning</Description>
                <RatePerUnit>30.00</RatePerUnit>
            </Reimbursement>
        </Reimbursements>
    </SetReimbursementsRequest>

Response:

<SetReimbursementsResponse xmlns="http://api.paycycle.com.au/v1.0">
        <Status>OK</Status>
        <ErrorDescription></ErrorDescription>
    </SetReimbursementsResponse>

UploadTimesheet

URL https://payroll.xero.com/API/Timesheet/Timesheet.svc/UploadTimesheet
Description This function uploads timesheet hours into a specific employees timesheet defined by earnings rate, tracking catagory and date.

Request:

<UploadTimesheetRequest xmlns="http://api.paycycle.com.au/v1.0">
    <ApiKey>00000000-0000-0000-0000-000000000000</ApiKey>
    <AuthorisationKey>00000000-0000-0000-0000-000000000000</AuthorisationKey> 
    <EmployeeID>2022</EmployeeID>
    <StartDate>2010-07-08T00:00:00</StartDate> 
    <EndDate>2010-07-14T00:00:00</EndDate> 
    <DeleteIfAlreadyExists>true</DeleteIfAlreadyExists> 
    <Lock>true</Lock>
    <TimesheetLines>
        <TimesheetLine> 
            <EarningsRateName>Ordinary Hours</EarningsRateName>
            <TimesheetCategoryName>Sydney</TimesheetCategoryName> 
            <TimesheetEntries>
                <NumberOfUnits>1</NumberOfUnits> 
                <NumberOfUnits>2</NumberOfUnits> 
                <NumberOfUnits>3</NumberOfUnits> 
                <NumberOfUnits>4</NumberOfUnits> 
                <NumberOfUnits>6</NumberOfUnits> 
                <NumberOfUnits>7</NumberOfUnits> 
                <NumberOfUnits>8</NumberOfUnits> 
            </TimesheetEntries>
        </TimesheetLine> 
        <TimesheetLine>
            <EarningsRateName>Overtime</EarningsRateName>
            <TimesheetCategoryName>Canberra</TimesheetCategoryName> 
            <TimesheetEntries>
                <NumberOfUnits>1.1</NumberOfUnits> 
                <NumberOfUnits>1.2</NumberOfUnits> 
                <NumberOfUnits>1.3</NumberOfUnits>
                <NumberOfUnits>1.4</NumberOfUnits> 
                <NumberOfUnits>1.2</NumberOfUnits>
                <NumberOfUnits>1.3</NumberOfUnits>
                <NumberOfUnits>2.4</NumberOfUnits> 
            </TimesheetEntries> 
        </TimesheetLine> 
    </TimesheetLines>
    </UploadTimesheetRequest>

Response:

<UploadTimesheetResponse xmlns="http://api.paycycle.com.au/v1.0">
    <Status>OK</Status>
    <ErrorDescription></ErrorDescription>
</UploadTimesheetResponse>
 
Do more with Xero
Partner with Xero
Get the Fact Sheet
Our Story