Calculation Commentary

A core design priciple of the PayRun.io API is transparency.

To this end as an artefact of every employee calculation in a pay run a comprehensive report is produced automatically detailing every calculation step, it's contextual reference data and the final result - we call this the calculation commentary report.

The intention of this report is to provide complete transparency into the process that culminates in an employee's final payslip. The report can used to debug unexpected annololies or satisfy an employee query.

Retrieving the Calculation Commentary report

The list of available calculation commentaries can either be retrieved via the employee or the payrun. There is a 1:1 relationship that exists between the commentary and a payrun, they are always returned in decending order.

Once you've identied the commentary report you'd like to retrieve you do so by issuing a [GET] request from the root employee and providing thr resource key.

curl -X GET \
  'https://api.test.payrun.io/Employer/ER001/Employee/EE001/Commentary/C001' \
  -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/Employer/ER001/Employee/EE001/Commentary/C001' \
  -H 'Accept: application/json' \
  -H 'Api-Version: default' \
  -H 'Authorization: {OAuthHeader}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-type: application/json'

Commentary Detail Example

For the full example that produced this commentary see Auto Enrolment example.

Begin Calculation
  Employee: Jane, Johnson
  Tax Period: M01-2017/18
  Pay Day: 2017-04-30 
  Pay Frequency: Monthly
  Start Pre-calculations Rules
    Rule matched: NI > Create Missing NI pay instruction
      New NI instruction for letter A created.
    Rule matched: Tax > Emergency Tax pay instruction
        New Tax instruction created with tax code: 1150L 1150L
    Total Rules: 16 - Excluded: 0 - Matched: 2
  End Pre-calculations Rules
  Begin Basic Pay Calculator
    Effective: Saturday, April 1, 2017 => Saturday, April 1, 2017
      Rate: 13.56 per Hour
      Units: 160.00
    Basic Pay: ROUND(13.56 * 160.00) = 2,169.60
  End Basic Pay Calculator
  Begin Tax Calculator
    Tax Code: 1150L
    Tax Basis: Week1Month1
    Taxable Pay: 2,169.60
      Taxable Deduction: 0.00
      Freepay: 959.09
      Taxable Pay: (Total Pay - Freepay)
      Taxable Pay: (2,169.60 - 959.09) = 1,210.51
        Tax Bands:
          | Name                     | Lower           | Upper           | Rate %          |
          |------------------------- |---------------- |---------------- |---------------- |
          | Basic Rate               | 0.00            | 33,500.00       | 20.00 %         |
          | Higher Rate              | 33,500.00       | 150,000.00      | 40.00 %         |
          | Additional Higher Rate   | 150,000.00      |                 | 45.00 %         |
          |------------------------- |---------------- |---------------- |---------------- |
      Calculate untaxed taxable period pay within bands
        Basic Rate               : (0.00 -> 33,500.00) = 1,210.00
        Higher Rate              : (33,500.00 -> 150,000.00) = 0.00
        Additional Higher Rate   : (150,000.00 -> ) = 0.00
      Calculate tax by band
        Basic Rate               : (1,210.00 * 20.00 %) = 242.0000
        Higher Rate              : (0.00 * 40.00 %) = 0.0000
        Additional Higher Rate   : (0.00 * 45.00 %) = 0.0000
      Total Tax: SUM(242.0000, 0.0000, 0.0000) = ROUNDPENNYDOWN(242.0000) = 242.00
    Total Period Tax  :  242.00
  End Tax Calculator
  Begin National Insurance Calculator
    Pay Frequency: Monthly
    Period: M01-2017/18
    Niable Pay: 2,169.60
    NI Letter: A
      NI Bandings
        | Name         | Lower        | Upper        | EE %         | ER %         | EE Rebate %  | ER Rebate %  |
        |------------- |------------- |------------- |------------- |------------- |------------- |------------- |
        | Below LEL    | 0.00         | 490.00       | 0.00 %       | 0.00 %       | 0.00 %       | 0.00 %       |
        | LEL to PT    | 490.00       | 680.00       | 0.00 %       | 0.00 %       | 0.00 %       | 0.00 %       |
        | PT to ST     | 680.00       | 680.00       | 12.00 %      | 0.00 %       | 0.00 %       | 0.00 %       |
        | ST to UEL    | 680.00       | 3,750.00     | 12.00 %      | 13.80 %      | 0.00 %       | 0.00 %       |
        | UEL to UST   | 3,750.00     | 3,750.00     | 2.00 %       | 13.80 %      | 0.00 %       | 0.00 %       |
        | Above UST    | 3,750.00     |              | 2.00 %       | 13.80 %      | 0.00 %       | 0.00 %       |
        |------------- |------------- |------------- |------------- |------------- |------------- |------------- |
    Calculate Niable pay within bands
      Below LEL  : (0.00 -> 490.00) = 490.00
      LEL to PT  : (490.00 -> 680.00) = 190.00
      PT to ST   : (680.00 -> 680.00) = 0.00
      ST to UEL  : (680.00 -> 3,750.00) = 1,489.60
      UEL to UST : (3,750.00 -> 3,750.00) = 0.00
      Above UST  : (3,750.00 -> ) = 0.00
    Calculate Employees NIC
      LEL to PT   : NIROUND(190.00 * 0.00 %) = 0.00
      PT to ST    : NIROUND(0.00 * 12.00 %) = 0.00
      ST to UEL   : NIROUND(1,489.60 * 12.00 %) = 178.75
      UEL to UST  : NIROUND(0.00 * 2.00 %) = 0.00
      Above UST   : NIROUND(0.00 * 2.00 %) = 0.00
    Employee NIC: SUM(0.00, 0.00, 178.75, 0.00, 0.00) = -178.75
    Employee NIC:  = -178.75
    Calculate Employers NIC
      LEL to PT   : NIROUND(190.00 * 0.00 %) = 0.00
      PT to ST    : NIROUND(0.00 * 0.00 %) = 0.00
      ST to UEL   : NIROUND(1,489.60 * 13.80 %) = 205.56
      UEL to UST  : NIROUND(0.00 * 13.80 %) = 0.00
      Above UST   : NIROUND(0.00 * 13.80 %) = 0.00
    Employer NIC: SUM(0.00, 0.00, 205.56, 0.00, 0.00) = -205.56
    Employer NIC: = -205.56
  End National Insurance Calculator
  Begin Auto Enrolment Assessment
    Step 1 - Assert auto enrolment is configured
      Employer revision exists
      Employer auto enrolment settings exist
      Pension revision exists
      Pension is AE compatible
    Step 2 - Gather assessment variables
      Pay run:                  PR001
      Current tax period:       M01-2017/18
      Payment date:             2017-04-30
      Auto enrolment pension:   AE Scheme
      Staging date:             2014-04-01
      Re-enrolment offset:      Month:0 Day:0
      Next re-enrolment date:   2017-04-01
      Employer deferment date:  None
      Date of birth:            1990-12-10
      22nd birthday:            2012-12-10
      Employment start date:    2013-04-01
      Employee deferment date:  None
      State pension start date: 2058-12-10
      State pension age:        68
      Assessment override:      None
      Assessment override date: None
      AE pension member:        False
      Alt pension member:       False
    Step 3 - Determine assessment date
      Assessment date:        2017-04-06 (tax period start date)
      Assessment tax period:  M01-2017/18 (based on assessment date)
      Age on assessment date: 26
      Payment frequency:      Monthly
      Qualifying earnings:    2,169.60
      AE lower threshold:     490.00
      AE trigger threshold:   833.00
      AE upper threshold:     3,750.00
    Step 4 - Determine if assessment is required
      Assessment date:             2017-04-06
      Employer staging date:       2014-04-01
      Employer postponement date:  None
      Result:                      Assessment required
    Step 5 - Determine employee worker type
      Employee age (26) falls within assessment range (16 to 74).
      Qualifying earnings above lower threshold. 2,169.60 > 490.00
      Qualifying earnings above trigger threshold. 2,169.60 > 833.00
      Employee age (26) falls within eligible job holder range (22 to SPA 68).
      Employee worker type: EligibleJobHolder
    Step 6 - Create auto enrolment assessment object
      Auto enrolment assessment object created
      No assessment override specified
    Step 7 - Determine final result
      Worker Type:         EligibleJobHolder
      Assessment Override: None
      Assessment Outcome:  AutomaticEnrolment
      Assessment Action:   Enrol
  End Auto Enrolment Assessment
  ####################################################################################################
  Auto enrolment assessment - Status Changed
    Assessment status: Enrol
    Re-running calculation to include new auto enrolment status
    Clearing previously calculated lines...
    Starting second pass calculation...
  ####################################################################################################
  Start Pre-calculations Rules
    Rule matched: AE > Enrolment Status Change
      New pension pay instruction created
    Total Rules: 16 - Excluded: 0 - Matched: 1
  End Pre-calculations Rules
  Begin Basic Pay Calculator
    Effective: Saturday, April 1, 2017 => Saturday, April 1, 2017
      Rate: 13.56 per Hour
      Units: 160.00
    Basic Pay: ROUND(13.56 * 160.00) = 2,169.60
  End Basic Pay Calculator
  Begin Tax Calculator
    Tax Code: 1150L
    Tax Basis: Week1Month1
    Taxable Pay: 2,169.60
      Taxable Deduction: 0.00
      Freepay: 959.09
      Taxable Pay: (Total Pay - Freepay)
      Taxable Pay: (2,169.60 - 959.09) = 1,210.51
        Tax Bands:
          | Name                     | Lower           | Upper           | Rate %          |
          |------------------------- |---------------- |---------------- |---------------- |
          | Basic Rate               | 0.00            | 33,500.00       | 20.00 %         |
          | Higher Rate              | 33,500.00       | 150,000.00      | 40.00 %         |
          | Additional Higher Rate   | 150,000.00      |                 | 45.00 %         |
          |------------------------- |---------------- |---------------- |---------------- |
      Calculate untaxed taxable period pay within bands
        Basic Rate               : (0.00 -> 33,500.00) = 1,210.00
        Higher Rate              : (33,500.00 -> 150,000.00) = 0.00
        Additional Higher Rate   : (150,000.00 -> ) = 0.00
      Calculate tax by band
        Basic Rate               : (1,210.00 * 20.00 %) = 242.0000
        Higher Rate              : (0.00 * 40.00 %) = 0.0000
        Additional Higher Rate   : (0.00 * 45.00 %) = 0.0000
      Total Tax: SUM(242.0000, 0.0000, 0.0000) = ROUNDPENNYDOWN(242.0000) = 242.00
    Total Period Tax  :  242.00
  End Tax Calculator
  Begin National Insurance Calculator
    Pay Frequency: Monthly
    Period: M01-2017/18
    Niable Pay: 2,169.60
    NI Letter: A
      NI Bandings
        | Name         | Lower        | Upper        | EE %         | ER %         | EE Rebate %  | ER Rebate %  |
        |------------- |------------- |------------- |------------- |------------- |------------- |------------- |
        | Below LEL    | 0.00         | 490.00       | 0.00 %       | 0.00 %       | 0.00 %       | 0.00 %       |
        | LEL to PT    | 490.00       | 680.00       | 0.00 %       | 0.00 %       | 0.00 %       | 0.00 %       |
        | PT to ST     | 680.00       | 680.00       | 12.00 %      | 0.00 %       | 0.00 %       | 0.00 %       |
        | ST to UEL    | 680.00       | 3,750.00     | 12.00 %      | 13.80 %      | 0.00 %       | 0.00 %       |
        | UEL to UST   | 3,750.00     | 3,750.00     | 2.00 %       | 13.80 %      | 0.00 %       | 0.00 %       |
        | Above UST    | 3,750.00     |              | 2.00 %       | 13.80 %      | 0.00 %       | 0.00 %       |
        |------------- |------------- |------------- |------------- |------------- |------------- |------------- |
    Calculate Niable pay within bands
      Below LEL  : (0.00 -> 490.00) = 490.00
      LEL to PT  : (490.00 -> 680.00) = 190.00
      PT to ST   : (680.00 -> 680.00) = 0.00
      ST to UEL  : (680.00 -> 3,750.00) = 1,489.60
      UEL to UST : (3,750.00 -> 3,750.00) = 0.00
      Above UST  : (3,750.00 -> ) = 0.00
    Calculate Employees NIC
      LEL to PT   : NIROUND(190.00 * 0.00 %) = 0.00
      PT to ST    : NIROUND(0.00 * 12.00 %) = 0.00
      ST to UEL   : NIROUND(1,489.60 * 12.00 %) = 178.75
      UEL to UST  : NIROUND(0.00 * 2.00 %) = 0.00
      Above UST   : NIROUND(0.00 * 2.00 %) = 0.00
    Employee NIC: SUM(0.00, 0.00, 178.75, 0.00, 0.00) = -178.75
    Employee NIC:  = -178.75
    Calculate Employers NIC
      LEL to PT   : NIROUND(190.00 * 0.00 %) = 0.00
      PT to ST    : NIROUND(0.00 * 0.00 %) = 0.00
      ST to UEL   : NIROUND(1,489.60 * 13.80 %) = 205.56
      UEL to UST  : NIROUND(0.00 * 13.80 %) = 0.00
      Above UST   : NIROUND(0.00 * 13.80 %) = 0.00
    Employer NIC: SUM(0.00, 0.00, 205.56, 0.00, 0.00) = -205.56
    Employer NIC: = -205.56
  End National Insurance Calculator
  Begin Relief at Source Pension Calculator
    Tax Period: M01-2017/18
    Pension Scheme: AE Scheme
    Pension Provider: NEST
    Taxation Method: ReliefAtSource
    Pension Deduction Date: 
    Pensionable Pay Codes:
      BASIC
    Pensionable Pay: 1,679.60
      Total Pensionable Pay: 2,169.60
      Lower Threshold: 490.00
      Upper Threshold: 3,750.00
      Pensionable Pay (Within Thresholds): 1,679.60
    Employee Contribution: 13.45
      Employee Contribution Percentage: 1.00 %
      Additional Voluntary Contribution Value: 0.00
      Statutory Relief At Source: 20.00 %
      Relief At Source: 3.35 = ROUNDDOWNPENNY(16.80 * 20.00 %)
      Adjusted Contribution Percentage: 0.80 % = 1.00 % - (1.00 % * 20.00 %)
      Employee Contribution: 13.45 = ROUND(1,679.60 * 0.80 %) + 0.00
    Employer Contribution: 16.80
      Employer Contribution Percentage: 1.00 %
      16.80 = (1,679.60 * 1.00 %)
  End Relief at Source Pension Calculator
    Payslip
      |------------------------------------- |------------- |------------------------------------- |------------- |
      | Payments                             | Amount £     | Deductions                           | Amount £     |
      |------------------------------------- |------------- |------------------------------------- |------------- |
      | Basic Pay (160.00 hours at 13.56)    | 2,169.60     | Tax                                  | -242.00      |
      |                                      |              | National Insurance                   | -178.75      |
      |                                      |              | Pension Contribution (RAS)           | -13.45       |
      |------------------------------------- |------------- |------------------------------------- |------------- |
      | NET PAY                              | 1,735.40     |
      |------------------------------------- |------------- |------------------------------------- |------------- |
      | This Period                          | Amount £     | Year to Date                         | Amount £     |
      |------------------------------------- |------------- |------------------------------------- |------------- |
      | Employer NI                          | -205.56      | Employer NI                          | -205.56      |
      | Employee NI                          | -178.75      | Employee NI                          | -178.75      |
      | Niable Pay                           | 2,169.60     | Niable Pay                           | 2,169.60     |
      | Taxable Pay                          | 2,169.60     | Taxable Pay                          | 2,169.60     |
      | Tax Paid                             | -242.00      | Tax Paid                             | -242.00      |
      |------------------------------------- |------------- |------------------------------------- |------------- |
    Payslip Report: /Report/PAYSLIP/run?EmployerKey=ER207&TaxYear=2017&TaxPeriod=1&EmployeeCodes=EMPAE1
End Calculation