Generating a Payslip

Each time an employee is paid, the employer is required to provide the employee with a payslip. PayRun.io provides several different versions of payslip data reports and an option to download a rendered PDF payslip.

This guides focuses on the payslip 3 report (which includes a PDF download option).

Executing the Payslip report

The payslip 3 report is a system defined report in the PayRun.io API, as with all reports you can request the report in either XML or JSON format.

To execute a report you must invoke the run endpoint and pass any required variables as query string parameters.

Variable Description Required
EmployerKey The target employer's resource unique key. Yes
PayScheduleKey The unique key of the pay schedule. Yes
TaxYear The tax year to be reported on. For tax year 2018/19 use: 2018 Yes
TaxPeriod The tax period to be reported on. If omitted, all periods are considered. No
EmployeeCodes A comma seperated list of the employee works codes. No
TransformDefinitionKey The report transformation key. Current options: Payslip-A5-Basic-Pdf No
StartIndex The starting index of the report. See paging results below for more information. No
MaxIndex The maximum index of the report. See paging results below for more information. No
PaymentDate The payment date to be reported on. No

This example demonstrates how to [GET] the report payslip output.

curl -X GET \
  'https://api.test.payrun.io/Report/PAYSLIP3/run?EmployerKey=ER001&PayScheduleKey=SCH001&TaxYear=2018&PaymentDate=2018-04-30' \
  -H 'Accept: application/xml' \
  -H 'Api-Version: default' \
  -H 'Authorization: {OAuthHeader}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-type: application/xml'
curl -X GET \
  'https://api.test.payrun.io/Report/PAYSLIP3/run?EmployerKey=ER001&PayScheduleKey=SCH001&TaxYear=2018&PaymentDate=2018-04-30' \
  -H 'Accept: application/json' \
  -H 'Api-Version: default' \
  -H 'Authorization: {OAuthHeader}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-type: application/json'

Response Example

<?xml version="1.0"?>
<Payslip3 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" Generated="2018-07-23T14:36:54" Duration="00:00:00.0625619" TotalIndexCount="1">
    <Parameters>
        <Employer>ER004</Employer>
        <PaySchedule>SCH004 [My Monthly - Monthly]</PaySchedule>
        <TaxYear>2018</TaxYear>
        <EmployeeCodes>TST004</EmployeeCodes>
    </Parameters>
    <Employer>
        <Name>Payslip Report Employer 4</Name>
        <PayeRef>451/A451</PayeRef>
    </Employer>
    <Employee Index="1" Code="TST004" Key="EE004" Name="Tom Dick" PayDate="2018-05-25" TaxPeriod="2">
        <Link href="/Employer/ER004/Employee/EE004/2018-04-06" />
        <NiNumber></NiNumber>
        <PaymentMethod>NotSet</PaymentMethod>
        <TaxCode>1185L / W1M1</TaxCode>
        <NiLetter>A</NiLetter>
        <Payments>
            <PayLine>
                <Description>Basic Pay</Description>
                <Value>5416.67</Value>
                <YTD>10833.34</YTD>
            </PayLine>
        </Payments>
        <Deductions>
            <PayLine>
                <Description>Tax</Description>
                <Value>-1196.20</Value>
                <YTD>2492.40</YTD>
            </PayLine>
            <PayLine>
                <Description>National Insurance</Description>
                <Value>-410.39</Value>
                <YTD>883.78</YTD>
            </PayLine>
        </Deductions>
        <PayRunTotals>
            <NiablePay>5416.67</NiablePay>
            <TaxablePay>5416.67</TaxablePay>
            <EENI>410.39</EENI>
            <ERNI>650.63</ERNI>
            <Tax>1196.20</Tax>
            <EEPension>0.00</EEPension>
            <ERPension>0.00</ERPension>
            <GrossPayments>5416.67</GrossPayments>
            <GrossDeductions>-1606.59</GrossDeductions>
            <Net>3810.08</Net>
        </PayRunTotals>
        <YearToDate>
            <NiablePay>11333.34</NiablePay>
            <TaxablePay>11333.34</TaxablePay>
            <EENI>883.78</EENI>
            <ERNI>1370.26</ERNI>
            <Tax>2492.40</Tax>
            <EEPension>0.00</EEPension>
            <ERPension>0.00</ERPension>
            <GrossPayments>11333.34</GrossPayments>
            <GrossDeductions>-3376.18</GrossDeductions>
            <Net>7957.16</Net>
        </YearToDate>
        <PreviousEmployment>
            <TaxablePay>0.00</TaxablePay>
            <Tax>0.00</Tax>
        </PreviousEmployment>
    </Employee>
</Payslip3>
{
    "Payslip3": {
        "@Generated": "2018-07-23T14:37:32",
        "@Duration": "00:00:00.0209227",
        "@TotalIndexCount": "1",
        "Parameters": {
            "Employer": "ER004",
            "PaySchedule": "SCH004 [My Monthly - Monthly]",
            "TaxYear": "2018",
            "EmployeeCodes": "TST004"
        },
        "Employer": {
            "Name": "Payslip Report Employer 4",
            "PayeRef": "451/A451"
        },
        "Employee": [
            {
                "@Index": "1",
                "@Code": "TST004",
                "@Key": "EE004",
                "@Name": "Tom Dick",
                "@PayDate": "2018-05-25",
                "@TaxPeriod": "2",
                "Link": {
                    "@href": "/Employer/ER004/Employee/EE004/2018-04-06"
                },
                "NiNumber": "",
                "PaymentMethod": "NotSet",
                "TaxCode": "1185L / W1M1",
                "NiLetter": "A",
                "Payments": {
                    "PayLine": [
                        {
                            "Description": "Basic Pay",
                            "Value": "5416.67",
                            "YTD": "10833.34"
                        }
                    ]
                },
                "Deductions": {
                    "PayLine": [
                        {
                            "Description": "Tax",
                            "Value": "-1196.20",
                            "YTD": "2492.40"
                        },
                        {
                            "Description": "National Insurance",
                            "Value": "-410.39",
                            "YTD": "883.78"
                        }
                    ]
                },
                "PayRunTotals": {
                    "NiablePay": "5416.67",
                    "TaxablePay": "5416.67",
                    "EENI": "410.39",
                    "ERNI": "650.63",
                    "Tax": "1196.20",
                    "EEPension": "0.00",
                    "ERPension": "0.00",
                    "GrossPayments": "5416.67",
                    "GrossDeductions": "-1606.59",
                    "Net": "3810.08"
                },
                "YearToDate": {
                    "NiablePay": "11333.34",
                    "TaxablePay": "11333.34",
                    "EENI": "883.78",
                    "ERNI": "1370.26",
                    "Tax": "2492.40",
                    "EEPension": "0.00",
                    "ERPension": "0.00",
                    "GrossPayments": "11333.34",
                    "GrossDeductions": "-3376.18",
                    "Net": "7957.16"
                },
                "PreviousEmployment": {
                    "TaxablePay": "0.00",
                    "Tax": "0.00"
                }
            }
        ]
    }
}

Exporting the Payslip as a PDF

The PayRun.io API supports exporting specific reports in a PDF format. This uses an API feature known as transforming; a specific system transform has been included for payslips.

Using the "Transform Definition Key" to control the PDF format

PDF output is controlled by including an additional query parameter on the report execution query string. Add "TransformDefinitionKey=Payslip-A5-Basic-Pdf" to return the report in PDF format.

This example demonstrates how to [GET] the Payslip report as a PDF, using the same P45 report parameters as used above.

curl -X GET \
  'https://api.test.payrun.io/Report/PAYSLIP3/run?EmployerKey=ER001&PayScheduleKey=SCH001&TaxYear=2018&PaymentDate=2018-04-30&TransformDefinitionKey=Payslip-A5-Basic-Pdf' \
  -H 'Accept: application/xml' \
  -H 'Api-Version: default' \
  -H 'Authorization: {OAuthHeader}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-type: application/xml'
curl -X GET \
  'https://api.test.payrun.io/Report/PAYSLIP3/run?EmployerKey=ER001&PayScheduleKey=SCH001&TaxYear=2018&PaymentDate=2018-04-30&TransformDefinitionKey=Payslip-A5-Basic-Pdf' \
  -H 'Accept: application/json' \
  -H 'Api-Version: default' \
  -H 'Authorization: {OAuthHeader}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-type: application/json'

The response from a successful transform request will always be a binary stream with a mime-type of application/pdf.

Example PDF Payslip

alt text

Controlling Paging With Indexes

When running reports and queries over laege datasets, it may be nescessary to return the results is sections to avoid timeout errors. In order to control the volume of report data, you can specify page subsets when generating reports.

Timeout Errors
The PayRun.io API includes a built in timeout limit when running reports. Report execution must complete within 30 seconds.

The payslip report includes 2 optional query string values:

  • Start Index
  • Max Index

The report also lets you know how many records (or indexes) were matched in the report. The total number of matched records is displayed in the TotalIndexCount attribute located in the report root element.

Example
The following example demonstrates how to retrieve paged subsets of a report output. Using a combination of Start (10) and Max (20) index, indexed records 10 to 20 are retrieved.

curl -X GET \
  'https://api.test.payrun.io/Report/PAYSLIP3/run?EmployerKey=ER001&PayScheduleKey=SCH001&TaxYear=2018&StartIndex=10&MaxIndex=20&TransformDefinitionKey=Payslip-A5-Basic-Pdf' \
  -H 'Accept: application/xml' \
  -H 'Api-Version: default' \
  -H 'Authorization: {OAuthHeader}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-type: application/xml'
curl -X GET \
  'https://api.test.payrun.io/Report/PAYSLIP3/run?EmployerKey=ER001&PayScheduleKey=SCH001&TaxYear=2018&StartIndex=10&MaxIndex=20&TransformDefinitionKey=Payslip-A5-Basic-Pdf' \
  -H 'Accept: application/json' \
  -H 'Api-Version: default' \
  -H 'Authorization: {OAuthHeader}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-type: application/json'

Specifying a StartIndex and ommitting the MaxIndex query parameter will return all records from the starting position.