Journals and Accounting in PayRun.io

The PayRun.io API offers a fully configurable journaling system that enables payroll accounting to match any third party system.

Journaling within the API is controlled by Journal Instructions. Theses instructions tell the API how to allocate payroll amounts into a ledger of nominal accounts and result in either a debit or credit.

Each time a pay run calculation completes, the journal instructions are processed. This results in a collection of Journal Lines that can then be reported on.

Created From Pay Runs and CIS Calculations

Journal lines can be generated from either pay runs or CIS calculations. Both these processes calculate employer liabilities and these values are tracked using journal lines, ledgers and accounts.

What Are Journal Lines?

A journal line models a single credit or debit entry into an account/NomCode.

What is an Account/NomCode?

An account (indicated by NomCode) is a grouping journal lines into a common liability. E.g. you can have a Tax account that groups all the tax liability journal lines.

What is a Ledger?

A ledger is a grouping of accounts that must be a balanced amount of credit and debit. A ledgers credits and debits must always sum up to zero.

Journal Instructions and Templates

The Journal Instructions can be defined in 2 places within the API. Instructions stored at the root application level are considered to be templates and those defined under the employer level are active instructions.

Template journal instructions are not executed during the pay run process and exist only to serve the generation of employer level instructions.

Employer level instructions are processed on every pay run (or CIS calculation) and can result in the generation of journal lines.

NomCode

The journal instructions require the inclusion of a NomCode value. This value denotes the target account for the calculated output and will be included on any generated journal lines.

Ledger Target

It is possible to support multiple ledgers within the journal line generation process. A ledger is a collection of associated journal lines and must provide a distinct balanced amount after each pay run.

Journal Lines

Journal Lines are generated during the pay run process. The journal instructions are used to allocate pay run calculated values into distinct lines. Journal lines indicate the target ledger and NomCode account.

The lines are considered child items of the pay run, so deletion of a pay run will also delete the associated journal lines. This means that a pay run re-calculation will also delete and re-calculate the journal lines.

Balancing Debit and Credit

Journal lines depict either a credit or debit towards a single account NomCode. In order to have a successful journalled pay run (or CIS calculation), the total amount of debits and credits (within a single ledger) must balance to zero. Failure to arrive at a zero ledger balance will result in a failed pay run or CIS calculation.

Warning
If your ledger debit and credit balance does not equal zero the pay run will fail!

How Journal Lines are Calculated

The PayRun.io pay run calculation and CIS calculation processes generate several API entities: Pay Lines, Report Lines, Auto Enrolment Assessments, Commentaries and CIS Lines.

When an employer has in-scope journal instructions, an additional post calculation step is executed; the journal calculation process.

The journal calculation process is broken down into the following steps.

  1. Create a data map of the calculated values.
  2. Find the in-scope journal instructions (they have start and end dates just like pay instructions).
  3. Execute the journal instruction expression against the data map to determine the credit or debit amount.
  4. Create journal lines for any non-zero calculated results.

What's a Credit and Debit?

Whether the journal line is a credit or debit is defined on it's impact to the employer.

The employer owns the accounts, so when paying out wages the amount is a debit (the employer account balance is depleted) but when reducing the amount paid out it is a credit (the employer account balance is increased).

The Data Map

In order to provide a tabular data structure, the calculated entity values (Pay lines, CIS lines and Report lines) are collected into a data set with 3 data tables.

Sparse Data
When tabulating the pay run entities, a column is introduced for all possible entity values and a row is added for each entity instance.

This results in data rows without complete column values and a sparsely populated data table.

Note: Empty column values are considered as zero when included in expression selections.

Data Tables

The data map includes 3 data tables:

Journal Instruction Expressions

The journal instruction has all the information needed to generate journal lines. This includes ledger, NomCode and account type (credit or debit). Another piece of important instruction information is the Expression.

Expressions are written a format similar to database SQL. The expression is executed against the data map and the resulting sum (if non zero) is applied to a new journal line.

The expression is comprised of 4 parts:

  1. SELECT - The output sum for the credit or debit amount.
  2. FROM - The table within the data map to query.
  3. WHERE - The filter clause used to determine which table rows should be selected.
  4. GROUP BY - An optional indication of how the data should be grouped. If omitted, then all matched rows are grouped into a single line result.

Example Expression

SELECT SUM([PayLine.Value]) * -1 
FROM [PayLines] 
WHERE [PayLine.Type] = 'PayLineTax' 
GROUP BY [Employee.Code]

Expression Breakdown

The example expression is broken down and explained below.

Select Section

SELECT SUM([PayLine.Value]) * -1

In the example SELECT expression, the value of column [PayLine.Value] is summed together and then inverted.

in this example, the sum value is inverted because tax is a deduction and therefore negative.

From Section

FROM [PayLines]

The example expression indicates that rows FROM the [PayLines] table should be selected.

Where Section

WHERE [PayLine.Type] = 'PayLineTax'

This WHERE clause will only select rows having a [PayLine.Type] column value matching PayLineTax. Note that use of apostrophes to wrap string values.

Where clauses are optional. If omitted, then the all rows within the data table will be included.

Group By Section

GROUP BY [Employee.Code]

The example expression includes an optional GROUP BY clause. When a grouping clause is included, rows are grouped together by common column values. Each group of rows are summed and written to a distinct journal line.

When grouping by column [Employee.Code], a journal line will be created for each distinct employee code column value within the select set of rows.

Appendix

Default Ledger

The PayRun.io API provides a default ledger collection of journal instructions. You can add the default ledger to an employer by invoking the below end point.

curl -X POST \
  'https://api.test.payrun.io/Employer/ER001/JournalInstructions/SystemDefaults' \
  -H 'Accept: application/xml' \
  -H 'Api-Version: default' \
  -H 'Authorization: {OAuthHeader}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-type: application/xml'
curl -X POST \
  'https://api.test.payrun.io/Employer/ER001/JournalInstructions/SystemDefaults' \
  -H 'Accept: application/json' \
  -H 'Api-Version: default' \
  -H 'Authorization: {OAuthHeader}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-type: application/json'

Pay Line Data Table

This data table includes all the available pay line properties. Each pay line is included in the data table as a distinct row.

Note: This table also includes some special values generated from Meta Data.

Table name: [PayLines]

Column Name Data Type
[Employee.Code] System.String
[Employee.FirstName] System.String
[Employee.LastName] System.String
[Employee.Region] System.String
[Employee.Territory] System.String
[Employee.Branch] System.String (From employee meta data)
[Employee.CostCentre] System.String (From employee meta data)
[Employee.Department] System.String (From employee meta data)
[PayCode.Benefit] System.Boolean
[PayCode.Niable] System.Boolean
[PayCode.Taxable] System.Boolean
[PayCode.Notional] System.Boolean
[PayCode.OriginalCode] System.String (From pay code meta data)
[PayCode.Type] System.String
[PayLine.Type] System.String
[PayLine.Code] System.String
[PayLine.Value] System.Decimal
[PayLine.Description] System.String
[PayLine.Generated] System.DateTime
[PayLine.Calculator] System.String
[PayLine.PaymentDate] System.DateTime
[PayLine.TaxYear] System.Int16
[PayLine.TaxPeriod] System.Int16
[PayLine.PayRunSequence] System.Int32
[PayLineAoe.Arrears] System.Decimal
[PayLineAoe.CaseNumber] System.String
[PayLineAoe.ArrestablePay] System.Decimal
[PayLineBenefit.TaxableAmount] System.Decimal
[PayLineBenefit.AccountingMethod] PayRunIO.Core.Enums.BenefitAccountingMethod
[PayLineCarBenefit.TaxableVehicle] System.Decimal
[PayLineCarBenefit.TaxableFuel] System.Decimal
[PayLineCarBenefit.VehicleRegistration] System.String
[PayLineCarBenefit.CashEquivalentVehicle] System.Decimal
[PayLineCarBenefit.CashEquivalentFuel] System.Decimal
[PayLineCarBenefit.DateRegistered] System.DateTime
[PayLineCarBenefit.FuelType] PayRunIO.Core.Enums.FuelType
[PayLineCarBenefit.ZeroEmissionsMileage] System.Int32
[PayLineCarBenefit.TaxableAmount] System.Decimal
[PayLineCarBenefit.AccountingMethod] PayRunIO.Core.Enums.BenefitAccountingMethod
[PayLineFurlough.EntitlementMonthStart] System.DateTime
[PayLineHoliday.UnitsDepleted] System.Decimal
[PayLineHoliday.UnitsAccrued] System.Decimal
[PayLineHoliday.UoM] PayRunIO.Core.Enums.UomBasicPay
[PayLineHoliday.YearEndDate] System.DateTime
[PayLineHoliday.ReclaimRate] System.Decimal
[PayLineLoan.Identifier] System.String
[PayLineNi.EmployerNI] System.Decimal
[PayLineNi.NiablePay] System.Decimal
[PayLineNi.ToPT] System.Decimal
[PayLineNi.ToST] System.Decimal
[PayLineNi.STtoUAP] System.Decimal
[PayLineNi.UAPtoUST] System.Decimal
[PayLineNi.ToUST] System.Decimal
[PayLineNi.ToAUST] System.Decimal
[PayLineNi.ToUEL] System.Decimal
[PayLineNi.AboveUEL] System.Decimal
[PayLineNi.NiLetter] System.String
[PayLineNi.LEL] System.Decimal
[PayLineNi.RebateEE] System.Decimal
[PayLineNi.RebateER] System.Decimal
[PayLineNi.DirCalculationMethod] PayRunIO.Core.Enums.DirCalculationMethod
[PayLineNi.WeeksAsDirector] System.Int32
[PayLineNi.PeriodsCovered] System.Int32
[PayLinePension.TaxationMethod] PayRunIO.Core.Enums.PensionTaxationMethod
[PayLinePension.EmployerContribution] System.Decimal
[PayLinePension.PensionablePay] System.Decimal
[PayLinePension.EmployerContributionPercent] System.Decimal
[PayLinePension.EmployeeContributionPercent] System.Decimal
[PayLinePension.EmployeeAdditionalVoluntaryCash] System.Decimal
[PayLinePension.EmployeeAdditionalVoluntaryPercent] System.Decimal
[PayLinePension.EmployerContributionCash] System.Decimal
[PayLinePension.EmployeeContributionCash] System.Decimal
[PayLinePension.ContributionDeductionDate] System.DateTime
[PayLinePension.SalarySacrifice] System.Boolean
[PayLinePension.EmployerNiSaving] System.Decimal
[PayLinePension.EmployeeAvcContribution] System.Decimal
[PayLinePension.PensionUniqueKey] System.String
[PayLineRate.Rate] System.Decimal
[PayLineRate.RateUoM] PayRunIO.Core.Enums.UomBasicPay
[PayLineRate.Units] System.Decimal
[PayLineRate.ProRataMethodApplied] PayRunIO.Core.Enums.ProRataMethod
[PayLineSap.HigherEarningRate] System.Decimal
[PayLineSap.StandardEarningRate] System.Decimal
[PayLineSap.WeeksUsed] System.Decimal
[PayLineSap.ExclusionReason] PayRunIO.Core.Enums.SapExclusionReason
[PayLineSap.KeepInTouchDaysUsed] System.Int32
[PayLineSap.AverageWeeklyEarnings] System.Decimal
[PayLineSap.AbsenceStart] System.DateTime
[PayLineSap.AbsenceEnd] System.DateTime
[PayLineShpp.WeeksUsed] System.Decimal
[PayLineShpp.ExclusionReason] PayRunIO.Core.Enums.ShppExclusionReason
[PayLineShpp.AverageWeeklyEarnings] System.Decimal
[PayLineShpp.AbsenceStart] System.DateTime
[PayLineShpp.AbsenceEnd] System.DateTime
[PayLineSmp.HigherEarningRate] System.Decimal
[PayLineSmp.StandardEarningRate] System.Decimal
[PayLineSmp.WeeksUsed] System.Decimal
[PayLineSmp.KeepInTouchDaysUsed] System.Int32
[PayLineSmp.ExclusionReason] PayRunIO.Core.Enums.SmpExclusionReason
[PayLineSmp.AverageWeeklyEarnings] System.Decimal
[PayLineSmp.AbsenceStart] System.DateTime
[PayLineSmp.AbsenceEnd] System.DateTime
[PayLineSpbp.WeeksUsed] System.Decimal
[PayLineSpbp.ExclusionReason] PayRunIO.Core.Enums.SpbpExclusionReason
[PayLineSpbp.AverageWeeklyEarnings] System.Decimal
[PayLineSpbp.AbsenceStart] System.DateTime
[PayLineSpbp.AbsenceEnd] System.DateTime
[PayLineSpp.WeeksUsed] System.Decimal
[PayLineSpp.ExclusionReason] PayRunIO.Core.Enums.SppExclusionReason
[PayLineSpp.AverageWeeklyEarnings] System.Decimal
[PayLineSpp.AbsenceStart] System.DateTime
[PayLineSpp.AbsenceEnd] System.DateTime
[PayLineSsp.WaitingDaysServed] System.Int32
[PayLineSsp.QualifyingDays] System.Int32
[PayLineSsp.DailyRate] System.Decimal
[PayLineSsp.WeeksUsed] System.Decimal
[PayLineSsp.ExclusionReason] PayRunIO.Core.Enums.SspExclusionReason
[PayLineSsp.SspType] PayRunIO.Core.Enums.SspType
[PayLineSsp.AverageWeeklyEarnings] System.Decimal
[PayLineSsp.AbsenceStart] System.DateTime
[PayLineSsp.AbsenceEnd] System.DateTime
[PayLineStudentLoan.StudentLoanCalculationMethod] PayRunIO.Core.Enums.StudentLoanCalculationMethod
[PayLineTax.TaxablePay] System.Decimal
[PayLineTax.TaxCode] System.String
[PayLineTax.TaxBasis] PayRunIO.Core.Enums.TaxBasis
[PayLineTermination.TaxableAmount] System.Decimal
[PayLineTermination.EmployerNI] System.Decimal
[PayLineTermination.TotalPayment] System.Decimal

Report Line Data Table

Calculation processes also generate employer centric Report Lines. The property values of the generated report lines are inserted into the report line data table.

This data table includes all the available report line properties. Each report line is included in the data table as a distinct row.

Table name: [ReportLines]

Column Name Data Type
[ReportLine.Type] System.String
[ReportLine.Value] System.Decimal
[ReportLine.Description] System.String
[ReportLine.Generated] System.DateTime
[ReportLine.TaxYear] System.Int16
[ReportLine.TaxMonth] System.Int16
[ReportLineApprenticeshipLevy.GrossNiablePay] System.Decimal
[ReportLineApprenticeshipLevy.Allowance] System.Decimal
[ReportLineApprenticeshipLevy.TotalAppLevy] System.Decimal
[ReportLinePension.PensionKey] System.String
[ReportLinePension.EmployerContribution] System.Decimal
[ReportLinePension.EmployeeContribution] System.Decimal
[ReportLinePension.Payment] System.Decimal
[ReportLineStatutoryRecovery.SmallEmployerRelief] System.Boolean
[ReportLineStatutoryRecovery.AbsenceReportCode] System.String
[ReportLineStatutoryRecovery.StatutoryTotal] System.Decimal
[ReportLineStatutoryRecovery.Compensation] System.Decimal
[ReportLineTaxSummary.GrossNetPay] System.Decimal
[ReportLineTaxSummary.GrossNiablePay] System.Decimal
[ReportLineTaxSummary.GrossEmployerNI] System.Decimal
[ReportLineTaxSummary.GrossEmployeeNI] System.Decimal
[ReportLineTaxSummary.GrossTaxablePay] System.Decimal
[ReportLineTaxSummary.GrossTax] System.Decimal
[ReportLineTaxSummary.StudentLoan] System.Decimal
[ReportLineTaxSummary.PostGraduateLoan] System.Decimal
[ReportLineTaxSummary.EmployerRealTimeNicClass1A] System.Decimal

CIS Line Data Table

CIS Calculations generate CIS Lines. The CIS line values are inserted into the CIS line data table.

This data table includes all the available CIS line properties. Each CIS line is included in the data table as a distinct row.

Note: This table also includes some special values generated from Meta Data.

Table name: [CISLines]

Column Name Data Type
[SubContractor.WorksNumber] System.String
[SubContractor.FirstName] System.String
[SubContractor.LastName] System.String
[SubContractor.TradingName] System.String
[SubContractor.Region] System.String
[SubContractor.Territory] System.String
[SubContractor.Branch] System.String (sub-contractor meta data)
[SubContractor.CostCentre] System.String (sub-contractor meta data)
[SubContractor.Department] System.String (sub-contractor meta data)
[CisLineType.LineType] System.String
[CisLineType.Description] System.String
[CisLine.Generated] System.DateTime
[CisLine.TaxTreatment] PayRunIO.Core.Enums.CisTaxTreatment
[CisLine.UOM] PayRunIO.Core.Enums.UomBasicPay
[CisLine.Units] System.Decimal
[CisLine.UnitRate] System.Decimal
[CisLine.VAT] System.Decimal
[CisLine.GrossPay] System.Decimal
[CisLine.CisDeduction] System.Decimal
[CisLine.Description] System.String
[CisLine.TaxYear] System.Int16
[CisLine.TaxPeriod] System.Int16
[CisLine.TaxMonth] System.Int16
[CisLine.PayFrequency] PayRunIO.Core.Enums.SubContractorPayFrequency