Pay Schemes¶

A pay scheme defines a pay arrangement which is a shared across workers, and which can be centrally modified.

A worker is enabled for a pay scheme using a Pay Item, based on a main Pay Definition, and which allows worker-specific values to be set in the usual way. The difference is that the main Pay Definition refers to a scheme by name.

Pay schemes are specialised Pay Definitions, and each is configured using key-value pairs:

{
    "key1": "a string value",
    "key2": 3.5,
    ...
    "foo": [1, 2, 3, 9],
    "bar": {
        "xyz": 1,
        "abc": "fff"
    }
}

Note that there is no Pay Item corresponding to the scheme Pay Definition; this also means that any key values set by the scheme can be changed subsequently and conveniently in one place.

paiyroll® uses schemes to describe the shared details of pay arrangements in various areas:

Types of Scheme¶
Scheme type	Usage
Holiday Schemes	Settings for absences where the start and end dates are known at the time of booking.
Sickness and other non-holiday absence Schemes	Settings for absences where the start date is known at the time of booking, but the end date is not.
OnDemand Schemes	Settings for limits and charges (such as how often on-demand may be used).
Pension Schemes	Settings for pension provider (such as scheme reference identifiers), and scheme limits and settings (such as the company contribution percentage).
Salary Schemes	Settings for salary calculations.
Timesheet Schemes	Configures the timesheets to be used (such as setting the granularity for time-of-attendance to 30-minutes, or the number of rates for piece-based timesheets to 3).

Schemes are described using key-value pairs. The keys and possible values in each case are described below.

Holiday Schemes¶

Holiday schemes are for booking time off. To use a Holiday scheme, create a Pay Definition based on the required Pay Template and a Workflow Definition to manage the booking process.

Note that the system prevents overlapping holiday bookings.

Universal Holiday¶

Each worker’s holiday pay item has the following inputs:

<implicit>:: Start/end dates etc. from booking workflow.
Annual entitlement:: The number of days holiday per year. The system automatically adjusts for employment start and end dates.
Per day or hour:: The value of a holiday day used when buying or selling holidays. If zero, is defaulted from any annual salary Pay Item / 226 at current date. Note that some asymmetry arises if N days are sold at per_diem X and later bought back at salary Y.
Holidayable earnings:: Earnings subject to holiday pay.
Migrated balance:: Use after import. If positive, this is used as a carry over value and the ‘carried_over’ state will be updated with this value. If negative, this value is interpreted as previously taken and the ‘taken’ state taken will be updated with this value. Assuming the default of reuse_zero, this input will be cleared on the next payrun. If a mistake is made, it can be re-entered for the next payrun.
Hours:: Hours worked.
Buy or sell:: Set to a positive number to buy holiday, negative number to sell. Has precedence over carry over when the year-end/leave date is reached. Validated on holiday sale against sell_limit (negative) or holiday buy against buy_limit (positive).
Scheme:: Holiday entitlement scheme definition.

This is how the pay item operates for different pay run types:

Pay run behaviour¶
Behaviour	Scheduled	Custom	On-demand
End date for which holiday entitlement is earned.	End of pay period.	Actual_t.	Not used.
Balancing payment for new-holiday-year (in first pay run of holiday year).	Yes.	Yes.	No.
Balancing payment for leaver (in first pay run with ending date after pay period start).	Yes.	Yes.	No.
Accumulate holidays taken, and buy-or-sell.	Yes.	Yes.	Yes.
Balance “Paid off on” date for new-holiday-year or leaver.	End of pay period.	Actual_t.	Not changed.
Holidayable earnings pay-out	Yes.	No.	No.

Universal AbsenceScheme¶

AbsenceScheme has the following scheme settings:

clazz:

Determines the remaining settings.

units:

Entitlement and Booking units

reset_date:

The day and month the holiday scheme is reset. 0001-01-01 uses each worker’s start date.

working_pattern:

How work is remunerated and contracted:

fixed:: Fixed regular number days or hours (default with no holiday pay).
variable:: Variable pay (regular overtime, commission or bonuses) (including holiday pay).
no:: No fixed hours (irregular, casual, zero-hours).

carry_limit:

Limit on the number of days or hours carried over when the holiday scheme is reset.

buy_limit:

Limit on the number of days or hours bought each year.

sell_limit:

Limit on the number of days or hours sold each year.

exceed_limit:

Limit on the number of days or hours bookable above year to date entitlement.

average_formula:

The formula used to calculate holiday pay:

all:

Pay in all pay periods is averaged in the calculation (default)

only_paid_w1:

Only pay for weeks that were paid regardless of pay frequency. Weekly pay is used directly for ‘w1’ schedules and weekly timesheets specify pay each week for all other schedules. If timesheets are missing, pay will be attributed to the earlier of pay period end or pay day of the schedule, which may not lead to the desired result.

Note: Monthly (m1, m3, m12) schedules must have a whole number of weeks in the pay period (end on the same weekday) for this option to operate. Otherwise the default ‘all’ formula will be used.

average_rate:

Total pay is divided by total days or hours (as set in Units).

average_period_weeks:

The period over which to average.

max_history_weeks:

The maximum history to record.

bookable_per_week:

Which days count as booked holidays:

working_days:: Use the employee working days (default)
ignore_public:: Use the employee working days, ignoring public holidays
0:: Zero uses the number of employee’s working days or hours.
1-8787:: Fixed number of days or hours per week.

units_per_week:

How many units (Days or Hours) is a week divided by. Zero uses the number of employee’s working days or hours.

entitlement_accrual:

Method for calculating entitlement:

pro_rata:: Pro-rata of holiday year x entitlement (default)
pro_rata_year2:: Pro-rata year 2 onwards, per month year 1:
worked_weeks:: Worked weeks only
percent:: Percent of Hours or Days worked

entitlement_percentage:

Accrue on percentage % of Days or Hours.

payout_balance:

When should a holiday balance be paid:

no_pay:: Not paid (default)
payout_leaving:: When leaving:
payout_year_end:: At holiday year end:
payout_always:: When leaving or year end

The scheme must be selected from:

paiyroll.pay.Universal.absence.holiday.AbsenceScheme

Example:

{
    "clazz": "paiyroll.pay.Universal.absence.holiday.AbsenceScheme",
    "working_pattern": "fixed",
    "reset_date": "2019-02-01",
    "carry_limit": 5,
    "buy_limit": 5,
    "sell_limit": 5
}

Workflows¶

The pay item requires a Workflow Definition based on paiyroll.flows.holiday.HolidayFlow.

Sickness and other non-holiday absence Schemes¶

Sickness schemes are for claiming pay due to illness and other non-holiday absences (for example, statutory maternity pay). To use a Sickness scheme, create a Pay Definition based on the required Pay Template and a Workflow Definition to manage the claim process.

Note that the system prevents overlapping sickness claims. Since sickness claims are typically started before the end is known, in practice this means that one claim must be ended before another can be started.

Occupational Sick Pay¶

In addition to any jurisdiction-specific Statutory pay for Sickness and other non-holiday absences, many employers choose to offer Occupational Sick Pay (OSP). Each Scheme defines one or more OSP entitlements summarised as follows:

A worker is eligible for an entitlement after the given number of weeks of employment.
The entitlement defines zero or more amounts payable from the start of an absence. Each amount is defined by a maximum number of weeks and how the payout for each pay period within those weeks is calculated.
The entitlement can also define an additional return bonus payout on return from the absence.
Any of the on absence or return bonus payouts can be marked as repayable if the worker leaves within a minimum number of weeks after the end of an absence (or leaves without returning). Recovering this balance is generally outside the scope of paiyroll® and must be handled using external methods, see below for more details.

There are also some overall Scheme-level settings.

An OSP entitlement describes what is to be paid out on each pay date matching a period of the absence. As shown, an absence can span multiple entitlements, and any return bonus is from the entitlement in effect at the end of the absence:

Generally, the Scheme, including the entitlement in effect, is re-evaluated on each Pay run. This means that if the entitlements are changed, existing absences will use the modified settings from the next Pay run.

Note

The main exception to this principle is that some payable basis values (see below) are calculated during the first pay run of an absence, and saved for later use.

OSP is evaluated as follows:

Separately for each type of Sickness and other non-holiday absence. For example, any OSP for GB SMP pays out independently of any OSP for GB SSP.
Separately from any associated statutory counterpart. For example, even if GB SSP does not pay out, any related OSP might still pay out.
In each pay run. Also, over-arching limiting of pay out across absences is performed based on the start date of the “first” absence, the total calendar days paid out since then, and the last paid-till date using these steps:
1. first_start and total_taken are reset:
  - If first_start is not set.
  - Else:
    - if rolling_limit is set and is greater than the “average absence” (see below).
    - if withhold_weeks is set and the “withholding period” is passed (see below).
    - Else when a new absence starts.
2. If total_taken exceeds the OSP entitlement, pay out is suppressed.
3. total_taken is incremented by the absence taken (for next time).

OSP Scheme settings¶

For OSP, the Scheme specifies:

rolling_limit:
Ignored if zero, else clears over-arching limiting if:
total_taken * 100 / (pp_start - first_start).days < rolling_limit
and so tends to limit the pay out on high absence percentages. Here are some example settings:

Absence rolling limit %¶

rolling_limit %

Equivalent absence

3

2 or fewer days in 13 weeks

2

3 or fewer days in 26 weeks

1

3 or fewer days in 52 weeks
withhold_weeks:
Ignored if zero, else clears over-arching limiting if:
total_taken > entitlement_days and (pp_start - paid_till) > withhold_weeks * 7
and so tends to limit the pay out on high absence totals. For example if the OSP entitlement is for 9 weeks and a worker has 3 absences of 4 weeks each, then some additional absences during and after the withheld period (of say 26 weeks):

Note

If neither rolling_limit nor withhold_weeks is set, the only limit is the OSP entitlement limit, and each absence pays out up to it.

OSP Entitlement settings¶

Within the Scheme, each OSP entitlement specifies:

eligible_after:

The minimum number of employed weeks. The applicable entitlement is the last one matched. If there is no match, no OSP will be paid.

on_absence:

Zero or more absence_pay rules. See description below.

on_return:

A return_bonus. See description below.

The on_absence absence_pay rules are in order of application. Each rule consists of:

payable_weeks:

The maximum number of weeks this absence_pay rule will be applied.

basis:

Jurisdiction-aware payment basis. The value is evaluated on each pay run unless otherwise specified:

Universal:flat_rate:

Pay a fixed lump sum amount per day of absence, set using the multiplier field.

Universal:salary:

Pay the salary per day of absence, times the multiplier field.

GB:average_earnings:

Scale 52/104 week average pay by the working pattern to a daily amount at the start of the absence. Pay the result per day of absence, times the multiplier field.

multiplier:

A multiplier for basis (or the fixed amount per working day if basis is Universal:flat_rate).

uplift:

Is this additional to, or an override of, the statutory provision?

repayable_before:

The amount paid will have to be repaid unless this number of weeks is worked on return. paiyroll® will deduct any OSP due at the repayable point, but this will often not cover the total owed. In any event, the balance owed will be marked on the pay slip but will not be further recovered by paiyroll®.

A return_bonus consists of:

basis:

Jurisdiction-aware payment basis. The value is evaluated in the pay run where the return is processed unless otherwise specified:

Universal:flat_rate:

Pay a fixed lump sum amount, set using the multiplier field.

Universal:salary:

Pay the salary for one pay period, times the multiplier field.

GB:average_earnings:

Scale 52/104 week average pay by the working pattern to a daily amount at the start of the absence. Pay the result per working day of the last pay period, times the multiplier field.

multiplier:

A multiplier for basis.

uplift:

As for absence_pay.

repayable_before:

As for absence_pay.

OSP Entitlement examples¶

Here are two example entitlements that might be combined. The first starts from 2 years of service:

#
# From two years service.
#
"eligible_after": 2 * 52,
"on_absence": [
    #
    # 8 weeks full pay, based on salary.
    # 8 weeks at half pay, based on salary, subject to repayment.
    #
    {"payable_weeks": 8, "basis": "Universal:salary", "multiplier": 1.0, "uplift": False,
     "repayable_before": 0},
    {"payable_weeks": 8, "basis": "Universal:salary", "multiplier": 0.5, "uplift": False,
     "repayable_before": 8},
],
"on_return": {
    #
    # Returner's bonus of 12 weeks at full pay.
    #
    "basis": "Universal:salary",
    "multiplier": 12.0,
    "uplift": False,
    "repayable_before": 0
}

and then from 5 years service:

#
# Five years service or more.
#
"eligible_after": 5 * 52,
"on_absence": [
    #
    # 12 weeks full pay, based on salary, added to statutory provision.
    # 12 weeks at half pay, based on salary, added to statutory provision, subject to
    # repayment.
    #
    {"payable_weeks": 12, "basis": "Universal:salary", "multiplier": 1.0, "uplift": True,
     "repayable_before": 0},
    {"payable_weeks": 12, "basis": "Universal:salary", "multiplier": 0.5, "uplift": True,
     "repayable_before": 12},
],
"on_return": {
    #
    # No returner's bonus.
    #
    "basis": "Universal:salary",
    "multiplier": 0,
    "uplift": False,
    "repayable_before": 0
}

Note that there is (implicitly) no entitlement to OSP for less than 2 years of service.

GB SMP (with occupational extensions)¶

Statutory Maternity Pay. Each worker’s pay item specifies:

<implicit>:: Start/end dates etc. from claim workflow.
Override:: Set to use the manual override.
Override value:: Manual override of calculated value. No entitlement tracking is performed.
AWE:: Average weekly earnings.
Scheme:: The scheme name.
Migrated YTD:: Migrated YTD value.

See the SMP eligibility rules and SMP guidance. Note:

Claims must be made within 12 weeks of the start date.
The system automatically disqualifies claims:
- If Average Weekly Earnings (AWE) fall below the minimum level.
- If the 26 week rule for Qualifying Week (QW) is not met for the current employment.
A claim usually starts when the worker takes planned maternity leave. If the leave starts unexpectedly (e.g. if the baby is born early, or if the worker is off work for a pregnancy-related illness in the 4 weeks before the week that the baby is due), delete the original claim and create a new claim with the new start date.

When a claim is ended, SMP is paid in complete weeks. The claim end must be set based on the reason for the end of the claim:

Claim endings¶
Ending reason	SMP claim end setting	SMP ending week
Worker leaves.	Set employment end date. Do not end SMP claim. If the Maternity Pay Period (MPP) has already started, you will have to continue paying SMP by manually enabling pay-after-end payments. See TBD for more information on the procedures for leavers.	Previous.
Worker is taken into legal custody.	Set SMP claim end to day before custody begins.	Previous.
Keep In Touch (KIT) day limit exceeded.	Set SMP claim end to day before KIT limit is exceeded.	Previous.
Worker dies.	Set SMP claim end to end of SMP week on or following date of death.	Given.

Even after an SMP claim has ended, the worker is not eligible for SSP until after the MPP is over. If the worker falls ill during the MPP, a new claim for SMP, based on the original pregnancy, must be made instead.
When entitlement to benefit ends, any Salary pay item will automatically resume (even if the claim is not ended by setting and approving an end date). The Salary can be zeroed to prevent overpayment if the worker is not expected to return.
Backdated pay rises are not supported.

GB SMPScheme¶

SMP has the following scheme settings:

clazz:: Determines the remaining settings.
entitlements:: How to configure Occupational Sick Pay
rolling_limit:: OSP rolling limit %. Zero to disable
withhold_weeks:: OSP withhold period in weeks. Zero to disable

The scheme must be selected from:

paiyroll.pay.GB.absence.SMPScheme

Example:

{
    "clazz": "paiyroll.pay.GB.absence.SMPScheme",
}

Workflows¶

The pay item requires a Workflow Definition based on paiyroll.flows.sickness.SicknessFlow.

GB SPBP (with occupational extensions)¶

Statutory Parental Bereavement Pay. Each worker’s pay item specifies:

<implicit>:: Start/end dates etc. from claim workflow.
Override:: Set to use the manual override.
Override value:: Manual override of calculated value. No entitlement tracking is performed.
AWE:: Average weekly earnings.
Scheme:: The scheme name.
Migrated YTD:: Migrated YTD value.

See Statutory Parental Bereavement Pay and Leave and Manually calculate SPBP. Note:

Claims must be made within 12 weeks of the start date.
The system automatically disqualifies claims:
- If Average Weekly Earnings (AWE) fall below the minimum level.
- If the 26 week rule for Relevant Week (RW) is not met for the current employment.
A claim usually starts when the worker takes planned bereavement leave.

When a claim is ended, SPBP is paid in complete weeks. The claim end must be set based on the reason for the end of the claim:

Claim endings¶
Ending reason	SPBP claim end setting	SPBP ending week
Worker leaves.	Set employment end date. Set SPBP claim end to the end date.	Previous.
Worker is taken into legal custody.	Set SPBP claim end to day before custody begins.	Previous.
Worker dies.	Set SPBP claim end to end of SPBP week on or following date of death.	Given.

When entitlement to benefit ends, any Salary pay item will automatically resume (even if the claim is not ended by setting and approving an end date). The Salary can be zeroed to prevent overpayment if the worker is not expected to return.
Adoption is not supported.
Backdated pay rises are not supported.

GB SPBPScheme¶

SPBP has the following scheme settings:

clazz:: Determines the remaining settings.
entitlements:: How to configure Occupational Sick Pay
rolling_limit:: OSP rolling limit %. Zero to disable
withhold_weeks:: OSP withhold period in weeks. Zero to disable

The scheme must be selected from:

paiyroll.pay.GB.absence.SPBPScheme

Example:

{
    "clazz": "paiyroll.pay.GB.absence.SPBPScheme",
}

Workflows¶

The pay item requires a Workflow Definition based on paiyroll.flows.sickness.SicknessFlow.

GB SPP (with occupational extensions)¶

Statutory Paternity Pay. Each worker’s pay item specifies:

<implicit>:: Start/end dates etc. from claim workflow.
Override:: Set to use the manual override.
Override value:: Manual override of calculated value. No entitlement tracking is performed.
AWE:: Average weekly earnings.
Scheme:: The scheme name.
Migrated YTD:: Migrated YTD value.

See the SPP eligibility rules and SPP guidance. Note:

Claims must be made within 12 weeks of the start date.
The system automatically disqualifies claims:
- If Average Weekly Earnings (AWE) fall below the minimum level.
- If the 26 week rule for Qualifying Week (QW) is not met for the current employment.
A claim usually starts when the worker takes planned paternity leave. If the leave starts unexpectedly (e.g. if the baby is born early), delete the original claim and create a new claim with the new start date.

When a claim is ended, SPP is paid in complete weeks. The claim end must be set based on the reason for the end of the claim:

Claim endings¶
Ending reason	SPP claim end setting	SPP ending week
Worker leaves.	Set employment end date. Set SPP claim end to the end date.	Previous.
Worker is taken into legal custody.	Set SPP claim end to day before custody begins.	Previous.
Worker dies.	Set SPP claim end to end of SPP week on or following date of death.	Given.

When entitlement to benefit ends, any Salary pay item will automatically resume (even if the claim is not ended by setting and approving an end date). The Salary can be zeroed to prevent overpayment if the worker is not expected to return.
Adoption is not supported.
Backdated pay rises are not supported.

GB SPPScheme¶

SPP has the following scheme settings:

clazz:: Determines the remaining settings.
entitlements:: How to configure Occupational Sick Pay
rolling_limit:: OSP rolling limit %. Zero to disable
withhold_weeks:: OSP withhold period in weeks. Zero to disable

The scheme must be selected from:

paiyroll.pay.GB.absence.SPPScheme

Example:

{
    "clazz": "paiyroll.pay.GB.absence.SPPScheme",
}

Workflows¶

The pay item requires a Workflow Definition based on paiyroll.flows.sickness.SicknessFlow.

GB SSP (with occupational extensions)¶

Statutory Sick Pay. Each worker’s pay item specifies:

<implicit>:: Start/end dates etc. from booking workflow.
AWE:: Average weekly earnings.
Scheme:: The scheme name.

Both qualifying and non-qualifying claims can be recorded. Note:

Claims must be made within 12 weeks of the start date.
The system automatically disqualifies claims:
- If Average Weekly Earnings (AWE) fall below the minimum level.
- If Statutory Maternity Pay (SMP) is in effect and the start is in the Maternity Pay Period (MPP).
- If Statutory Paternity Pay (SPP) is in effect and the start is in the Paternity Pay Period (PPP).
When entitlement to benefit ends, any Salary pay item will automatically resume (even if the claim is not ended by setting and approving an end date). The Salary can be zeroed to prevent overpayment if the worker is not expected to return.
If a worker leaves, claims are truncated to the end date.
SSP is not payable after a worker dies. In this event, mark them as having left on the date the event.

GB SSPScheme¶

SSP has the following scheme settings:

clazz:: Determines the remaining settings.
entitlements:: How to configure Occupational Sick Pay
rolling_limit:: OSP rolling limit %. Zero to disable
withhold_weeks:: OSP withhold period in weeks. Zero to disable

The scheme must be selected from:

paiyroll.pay.GB.absence.SSPScheme

Example:

{
    "clazz": "paiyroll.pay.GB.absence.SSPScheme",
}

Universal sickness (with occupational extensions)¶

Used for absences which do not have a statutory basis such as sabbaticals, compassionate leave and so on. Each worker’s pay item specifies:

<implicit>:: Start/end dates etc. from booking workflow.
Scheme:: The scheme.

It is recommended that separate Pay Definitions be set up with names and descriptions reflecting the intended usage; this will ensure that pay slips have suitably descriptive line items.

Universal Sickness Scheme¶

Universal absence has the following scheme settings:

clazz:: Determines the remaining settings.
entitlements:: How to configure Occupational Sick Pay
rolling_limit:: OSP rolling limit %. Zero to disable
withhold_weeks:: OSP withhold period in weeks. Zero to disable

The scheme must be selected from:

paiyroll.pay.Universal.absence.sickness.AbsenceOccupationalScheme

Example:

{
    "clazz": "paiyroll.pay.Universal.absence.sickness.AbsenceOccupationalScheme",
}

OnDemand Schemes¶

OnDemand schemes are for booking time off. To use the OnDemand scheme, create a Pay Definition based on the required Pay Template.

Universal OnDemand pay¶

Each worker’s pay item specifies:

Available pay:: How much pay is available?
Scheme:: On-Demand scheme definition.

Notes:

The following Pay Templates include specific support for OnDemand:
- Universal Holiday
- Universal Salary
- GB PAYE
- GB NIC
- GB AE
- GB Termination
- GB SMP, SPBP, SPP, SSP
- GB Attachments. Care must be taken when configuring OnDemand for a worker who has attachments configured too. See GB Attachment of Earnings and Student Loans (Garnishes) for details.

Universal OnDemandScheme¶

OnDemandScheme has the following scheme settings:

clazz:

Determines the remaining settings.

processed_on:

Except on frozen days, requests are processed:

every_day
working_days

deadline:

After this UTC hour, processing may be delayed, subject to processed_on.

max_withdrawals:

Absolute limit of withdrawals between pay dates.

free_withdrawals:

Withdrawals between pay dates that are free to the employee (i.e. don’t incur withdrawal_fee).

withdrawal_fee:

Per-withdrawal charge to Employee after free_withdrawals.

payment_eta:

An indication of how long after being processed payment should arrive in the Employee’s account.

max_value:

A value limit on any request. Full available pay if zero.

max_percentage:

A percentage limit on any request. Not used if 100.

The scheme must be selected from:

paiyroll.pay.Universal.ondemand.OnDemandScheme

Pension Schemes¶

Pension schemes are for managing pension contributions. To use a Pension scheme, create a Pay Definition based on the required Pay Template.

GB AE¶

Auto Enrolment. Each worker’s pay item specifies:

No tax relief:: tax relief: Normally False, but can be set if the worker is not eligible for tax relief.
Awaiting NI:: NI: Overseas national awaiting their NI (used by NEST or other report submissions only).
QE:: Qualifying Earnings (QE) used as the basis for AE.
Worker %:: %: Worker % contribution between 0 and 100.
Company %:: %: Company % scheme override between 0 and 100. If zero, scheme setting applies.
PE:: Pensionable Earnings (PE) as the basis for AE.
Worker adj:: adj: Manual adjustment to computed worker deduction.
Company adj:: adj: Manual adjustment to computed company contribution.
Scheme:: Name of the Scheme used for AE.
Migrated status:: status: Status, e.g. Auto enrolled for migrated employees.
Refund ref:: ref: Set to the reference provided by the pension provider to enable a refund.
Reference:: Optional pension provider reference.
Opt-out date:: date: Opt-out date provided by the pension provider. Only enter if within 1 calendar month. Invalid notices can extend the opt-out period to 6 weeks.
Migrated date:: date: Can be the Enrol date or Deferral date for imported workers. Otherwise None.
Opt-in date:: date: Opt-in date if a worker asks to opt-in. Otherwise None.

Notes:

For a migrated employee, the Migrated status and Migrated enrol date must be set appropriately.
When an employee is leaving, setting the end date will prevent any automatic enrolment.
On the third anniversary of your staging date, the AE Pay Item will automatically assess workers who are not enrolled and automatically enrol them if applicable.
You must not process a refund for a worker unless notified by the pension provider.

If notified by the pension provider that a refund is due, set the refund reference on the AE Pay Item for the worker concerned. The amounts due to the worker and the Company are calculated automatically. In any case, no refund will be issued if the opt-out date is more than 12 weeks from the enrol date.

GB AE Common Scheme Settings¶

The scheme settings for Auto Enrolment have some common elements:

prp_alignment:

Pay Reference Periods (PRPs) are aligned are aligned to tax or calendar periods:

tax:: Means the HMRC tax calendar (default).
calendar:: Means the normal pay period used on the schedule.

duties_start:

The postponement approach when duties for AE start:

none:: No postponement (default).
maximum:: Maximum postponement of 3 months.
next_prp:: Postpone to the start of the next PRP.
latest_prp:: Postpone to the start of the latest allowable PRP.

employment_start:

The postponement approach for the first day of employment. See above for the allowed values.

eligible_jobholder:

The postponement approach when a worker triggers as an eligible jobholder. See above for the allowed values.

company_contribution:

The company contribution percentage.

group:

Names a group of workers.

Examples:

{
    "prp_alignment": "tax",
    "eligible jobholder": "maximum",
    "employment start": "maximum",
    "duties start": "maximum",
    "company_contribution": "3"
}

{
    "prp_alignment": "calendar",
    "eligible jobholder": "latest_prp",
    "employment start": "latest_prp",
    "duties start": "latest_prp",
    "company_contribution": "3.1"
}

{
    "eligible jobholder": "maximum",
    "employment start": "latest_prp",
    "duties start": "none",
    "company_contribution": "3.75"
}

GB AEGONPensionScheme¶

AEGON Auto Enrolment has the following scheme settings:

clazz:: Determines the remaining settings.
name:: The name of the scheme.
reference:: A reference for the scheme.
type:: Net pay arrangement (NPA) and Salary sacrifice are taken from gross pay; Relief at source (RAS) is taken from net pay.
age_stop:: Age to stop pension contributions.
contribute_after_end:: Continue contributions if pay after end
prp_alignment:: The Pay Reference Period (PRP) is aligned to tax weeks/months or calendar pay schedule.
duties_start:: Postponement from duties start
employment_start:: Postponement from employment start
eligible_jobholder:: Postponement from eligible jobholder
company_contribution:: Percentage company contribution
matching:: Match Company contribution to worker %
multiplier:: Uplift (matched) company contribution by worker % multiplier
group:: The groupname.
contribution_basis:: The basis of contributions.
on_leave_pay_basis:: Company contribution pay basis when on leave
round_up:: Round up or normal rounding

GB AvivaPensionScheme¶

Aviva Auto Enrolment has the following scheme settings:

clazz:: Determines the remaining settings.
name:: The name of the scheme.
reference:: A reference for the scheme.
type:: Net pay arrangement (NPA) and Salary sacrifice are taken from gross pay; Relief at source (RAS) is taken from net pay.
age_stop:: Age to stop pension contributions.
contribute_after_end:: Continue contributions if pay after end
prp_alignment:: The Pay Reference Period (PRP) is aligned to tax weeks/months or calendar pay schedule.
duties_start:: Postponement from duties start
employment_start:: Postponement from employment start
eligible_jobholder:: Postponement from eligible jobholder
company_contribution:: Percentage company contribution
matching:: Match Company contribution to worker %
multiplier:: Uplift (matched) company contribution by worker % multiplier
group:: The groupname.
contribution_basis:: The basis of contributions.
on_leave_pay_basis:: Company contribution pay basis when on leave
round_up:: Round up or normal rounding

GB NESTPensionScheme¶

NEST Auto Enrolment has the following scheme settings:

clazz:: Determines the remaining settings.
name:: The name of the scheme.
reference:: A reference for the scheme.
type:: Net pay arrangement (NPA) and Salary sacrifice are taken from gross pay; Relief at source (RAS) is taken from net pay.
age_stop:: Age to stop pension contributions.
contribute_after_end:: Continue contributions if pay after end
prp_alignment:: The Pay Reference Period (PRP) is aligned to tax weeks/months or calendar pay schedule.
duties_start:: Postponement from duties start
employment_start:: Postponement from employment start
eligible_jobholder:: Postponement from eligible jobholder
company_contribution:: Percentage company contribution
matching:: Match Company contribution to worker %
multiplier:: Uplift (matched) company contribution by worker % multiplier
group:: The groupname.
contribution_basis:: The basis of contributions.
on_leave_pay_basis:: Company contribution pay basis when on leave
round_up:: Round up or normal rounding
payment_source:: The NEST payment source.

Example:

{
    "clazz": "paiyroll.pay.GB.pension.NESTPensionScheme",
    "name": "NEST Auto Enrolment",
    "reference": "EMP123456789",
    "type": "relief_at_source",
    "eligible jobholder": "maximum",
    "employment start": "maximum",
    "duties start": "maximum",
    "group": "C2",
    "payment_source": "NW1"
}

GB NowPensionScheme¶

Now Pensions Auto Enrolment has the following scheme settings:

clazz:: Determines the remaining settings.
name:: The name of the scheme.
reference:: A reference for the scheme.
type:: Net pay arrangement (NPA) and Salary sacrifice are taken from gross pay; Relief at source (RAS) is taken from net pay.
age_stop:: Age to stop pension contributions.
contribute_after_end:: Continue contributions if pay after end
prp_alignment:: The Pay Reference Period (PRP) is aligned to tax weeks/months or calendar pay schedule.
duties_start:: Postponement from duties start
employment_start:: Postponement from employment start
eligible_jobholder:: Postponement from eligible jobholder
company_contribution:: Percentage company contribution
matching:: Match Company contribution to worker %
multiplier:: Uplift (matched) company contribution by worker % multiplier
group:: The groupname.
contribution_basis:: The basis of contributions.
on_leave_pay_basis:: Company contribution pay basis when on leave
round_up:: Round up or normal rounding
scheme_code:: Scheme codes confirmed on scheme summary issued at sign up.

GB OptionsPensionsScheme¶

Note:

The reference is the scheme number allocated to you by Options UK, also known as the EPSR number.

Options Pensions Auto Enrolment has the following scheme settings:

clazz:: Determines the remaining settings.
name:: The name of the scheme.
reference:: A reference for the scheme.
type:: Net pay arrangement (NPA) and Salary sacrifice are taken from gross pay; Relief at source (RAS) is taken from net pay.
age_stop:: Age to stop pension contributions.
contribute_after_end:: Continue contributions if pay after end
prp_alignment:: The Pay Reference Period (PRP) is aligned to tax weeks/months or calendar pay schedule.
duties_start:: Postponement from duties start
employment_start:: Postponement from employment start
eligible_jobholder:: Postponement from eligible jobholder
company_contribution:: Percentage company contribution
matching:: Match Company contribution to worker %
multiplier:: Uplift (matched) company contribution by worker % multiplier
group:: The groupname.
contribution_basis:: The basis of contributions.
on_leave_pay_basis:: Company contribution pay basis when on leave
round_up:: Round up or normal rounding

GB PeoplesPensionScheme¶

The People’s Pension Auto Enrolment has the following scheme settings:

clazz:: Determines the remaining settings.
name:: The name of the scheme.
reference:: A reference for the scheme.
type:: Net pay arrangement (NPA) and Salary sacrifice are taken from gross pay; Relief at source (RAS) is taken from net pay.
age_stop:: Age to stop pension contributions.
contribute_after_end:: Continue contributions if pay after end
prp_alignment:: The Pay Reference Period (PRP) is aligned to tax weeks/months or calendar pay schedule.
duties_start:: Postponement from duties start
employment_start:: Postponement from employment start
eligible_jobholder:: Postponement from eligible jobholder
company_contribution:: Percentage company contribution
matching:: Match Company contribution to worker %
multiplier:: Uplift (matched) company contribution by worker % multiplier
group:: The groupname.
contribution_basis:: The basis of contributions.
on_leave_pay_basis:: Company contribution pay basis when on leave
round_up:: Round up or normal rounding

Example:

{
    "clazz": "paiyroll.pay.GB.pension.PensionPensionScheme",
    "name": "Workshop weekly",
    "reference": "EMP123456789",
    "type": "relief_at_source",
    "contribution_basis": "banded"
}

Note that The People’s Pension requires that all schemes for a given Company use the same “type”.

GB RoyalLondonPensionScheme¶

Royal London Auto Enrolment has the following scheme settings:

clazz:: Determines the remaining settings.
name:: The name of the scheme.
reference:: A reference for the scheme.
type:: Net pay arrangement (NPA) and Salary sacrifice are taken from gross pay; Relief at source (RAS) is taken from net pay.
age_stop:: Age to stop pension contributions.
contribute_after_end:: Continue contributions if pay after end
prp_alignment:: The Pay Reference Period (PRP) is aligned to tax weeks/months or calendar pay schedule.
duties_start:: Postponement from duties start
employment_start:: Postponement from employment start
eligible_jobholder:: Postponement from eligible jobholder
company_contribution:: Percentage company contribution
matching:: Match Company contribution to worker %
multiplier:: Uplift (matched) company contribution by worker % multiplier
group:: The groupname.
contribution_basis:: The basis of contributions.
on_leave_pay_basis:: Company contribution pay basis when on leave
round_up:: Round up or normal rounding

Note

Group: The Group should be set to the appropriate Category identifier if your scheme has multiple categories (groups of workers).

GB Salvus Master Trust¶

Salvus Master Trust has the following scheme settings:

clazz:: Determines the remaining settings.
name:: The name of the scheme.
reference:: A reference for the scheme.
type:: Net pay arrangement (NPA) and Salary sacrifice are taken from gross pay; Relief at source (RAS) is taken from net pay.
age_stop:: Age to stop pension contributions.
contribute_after_end:: Continue contributions if pay after end
prp_alignment:: The Pay Reference Period (PRP) is aligned to tax weeks/months or calendar pay schedule.
duties_start:: Postponement from duties start
employment_start:: Postponement from employment start
eligible_jobholder:: Postponement from eligible jobholder
company_contribution:: Percentage company contribution
matching:: Match Company contribution to worker %
multiplier:: Uplift (matched) company contribution by worker % multiplier
group:: The groupname.
contribution_basis:: The basis of contributions.
on_leave_pay_basis:: Company contribution pay basis when on leave
round_up:: Round up or normal rounding

GB ScottishWidowsPensionScheme¶

Scottish Widows Auto Enrolment has the following scheme settings:

clazz:: Determines the remaining settings.
name:: The name of the scheme.
reference:: A reference for the scheme.
type:: Net pay arrangement (NPA) and Salary sacrifice are taken from gross pay; Relief at source (RAS) is taken from net pay.
age_stop:: Age to stop pension contributions.
contribute_after_end:: Continue contributions if pay after end
prp_alignment:: The Pay Reference Period (PRP) is aligned to tax weeks/months or calendar pay schedule.
duties_start:: Postponement from duties start
employment_start:: Postponement from employment start
eligible_jobholder:: Postponement from eligible jobholder
company_contribution:: Percentage company contribution
matching:: Match Company contribution to worker %
multiplier:: Uplift (matched) company contribution by worker % multiplier
group:: The groupname.
contribution_basis:: The basis of contributions.
on_leave_pay_basis:: Company contribution pay basis when on leave
round_up:: Round up or normal rounding

GB ScottishWidowsAssistMePensionScheme¶

Scottish Widows AssistMe Auto Enrolment has the following scheme settings:

clazz:: Determines the remaining settings.
name:: The name of the scheme.
reference:: A reference for the scheme.
type:: Net pay arrangement (NPA) and Salary sacrifice are taken from gross pay; Relief at source (RAS) is taken from net pay.
age_stop:: Age to stop pension contributions.
contribute_after_end:: Continue contributions if pay after end
prp_alignment:: The Pay Reference Period (PRP) is aligned to tax weeks/months or calendar pay schedule.
duties_start:: Postponement from duties start
employment_start:: Postponement from employment start
eligible_jobholder:: Postponement from eligible jobholder
company_contribution:: Percentage company contribution
matching:: Match Company contribution to worker %
multiplier:: Uplift (matched) company contribution by worker % multiplier
group:: The groupname.
contribution_basis:: The basis of contributions.
on_leave_pay_basis:: Company contribution pay basis when on leave
round_up:: Round up or normal rounding
pay_group:: Name of the Pay Group that employees belongs in

GB SmartPensionScheme¶

Smart Pension Auto Enrolment has the following scheme settings:

clazz:: Determines the remaining settings.
name:: The name of the scheme.
reference:: A reference for the scheme.
type:: Net pay arrangement (NPA) and Salary sacrifice are taken from gross pay; Relief at source (RAS) is taken from net pay.
age_stop:: Age to stop pension contributions.
contribute_after_end:: Continue contributions if pay after end
prp_alignment:: The Pay Reference Period (PRP) is aligned to tax weeks/months or calendar pay schedule.
duties_start:: Postponement from duties start
employment_start:: Postponement from employment start
eligible_jobholder:: Postponement from eligible jobholder
company_contribution:: Percentage company contribution
matching:: Match Company contribution to worker %
multiplier:: Uplift (matched) company contribution by worker % multiplier
group:: The groupname.
contribution_basis:: The basis of contributions.
on_leave_pay_basis:: Company contribution pay basis when on leave
round_up:: Round up or normal rounding

Example:

{
    "clazz": "paiyroll.pay.GB.pension.SmartPensionScheme",
    "name": "SmartPension Auto Enrolment",
    "reference": "12011089",
    "type": "net_pay",
    "contribution_basis": "unbanded",
    "eligible jobholder": "maximum",
    "employment start": "latest_prp",
    "duties start": "next_prp",
    "group": "abc"
}

GB StandardLifePensionScheme¶

Standard Life Auto Enrolment has the following scheme settings:

clazz:: Determines the remaining settings.
name:: The name of the scheme.
reference:: A reference for the scheme.
type:: Net pay arrangement (NPA) and Salary sacrifice are taken from gross pay; Relief at source (RAS) is taken from net pay.
age_stop:: Age to stop pension contributions.
contribute_after_end:: Continue contributions if pay after end
prp_alignment:: The Pay Reference Period (PRP) is aligned to tax weeks/months or calendar pay schedule.
duties_start:: Postponement from duties start
employment_start:: Postponement from employment start
eligible_jobholder:: Postponement from eligible jobholder
company_contribution:: Percentage company contribution
matching:: Match Company contribution to worker %
multiplier:: Uplift (matched) company contribution by worker % multiplier
group:: The groupname.
contribution_basis:: The basis of contributions.
on_leave_pay_basis:: Company contribution pay basis when on leave
round_up:: Round up or normal rounding

GB TPSPensionScheme¶

TPS Auto Enrolment has the following scheme settings:

clazz:: Determines the remaining settings.
name:: The name of the scheme.
reference:: A reference for the scheme.
type:: Net pay arrangement (NPA) and Salary sacrifice are taken from gross pay; Relief at source (RAS) is taken from net pay.
age_stop:: Age to stop pension contributions.
contribute_after_end:: Continue contributions if pay after end
prp_alignment:: The Pay Reference Period (PRP) is aligned to tax weeks/months or calendar pay schedule.
duties_start:: Postponement from duties start
employment_start:: Postponement from employment start
eligible_jobholder:: Postponement from eligible jobholder
full_part_time:: Full/Part-time.
payroll_provider_number:: Optional e.g. 750/4005.

GB TruePotentialPensionScheme¶

True Potential Auto Enrolment has the following scheme settings:

clazz:: Determines the remaining settings.
name:: The name of the scheme.
reference:: A reference for the scheme.
type:: Net pay arrangement (NPA) and Salary sacrifice are taken from gross pay; Relief at source (RAS) is taken from net pay.
age_stop:: Age to stop pension contributions.
contribute_after_end:: Continue contributions if pay after end
prp_alignment:: The Pay Reference Period (PRP) is aligned to tax weeks/months or calendar pay schedule.
duties_start:: Postponement from duties start
employment_start:: Postponement from employment start
eligible_jobholder:: Postponement from eligible jobholder
company_contribution:: Percentage company contribution
matching:: Match Company contribution to worker %
multiplier:: Uplift (matched) company contribution by worker % multiplier
group:: The groupname.
contribution_basis:: The basis of contributions.
on_leave_pay_basis:: Company contribution pay basis when on leave
round_up:: Round up or normal rounding

Universal Pension contribution¶

Contributory scheme with employer match. Each worker’s pay item specifies:

Pensionable pay:: Basis of pension.
Worker %:: The percentage paid by the worker.
Company %:: The base percentage paid by the employer.
Maximum match %:: How much of Worker % will the employer match?
Lower:: Earnings below the lower limit contribute zero.
Upper:: Earnings above are ignored.
Scheme:: Pension scheme definition.

GB PensionScheme¶

Contributory scheme has the following scheme settings:

clazz:: Determines the remaining settings.
name:: The name of the scheme.
reference:: A reference for the scheme.
type:: Net pay arrangement (NPA) and Salary sacrifice are taken from gross pay; Relief at source (RAS) is taken from net pay.
age_stop:: Age to stop pension contributions.
contribute_after_end:: Continue contributions if pay after end

Example:

{
    "clazz": "paiyroll.pay.GB.pension.PensionScheme",
    "name": "Prudence Co 1",
    "reference": "999/1/123",
}

Salary Schemes¶

Salary schemes are for annual salary. To use the Salary scheme, create a Pay Definition based on the required Pay Template.

Universal Salary¶

Implementation of annual salary. The value here can also be used to derive a default per-diem value for Holiday buy/sell calculations and Occupational Sick Pay. Each worker’s pay item specifies:

Base Salary:: Current annual salary.
Absence days:: Holidays and sick days remunerated elsewhere and not to be paid by this opcode.
Next Base Salary:: The annual salary from Next Effective Date.
Scheme:: Salary scheme definition.
Next Effective Date:: Date when Next Base Salary takes effect.

The salary calculation operates in two modes, one for a whole pay period and another for fractional pay periods.

Whole pay periods. Applies when pay is due for a complete pay period. The Base Salary is divided into equals parts for each pay period. Note that for month-based pay periods, the result is the same even for months of different lengths.
Fractional pay periods. Applies when:
- A new starter has a start date not aligned to the start of a pay period.
- A leaver has an end date not aligned to the end of a pay period.
- Custom or On-demand pay runs are used, and for any subsequent Scheduled pay run.
- A period of absence is involved.
The Base Salary is divided into a per-diem value using the per_diem_basis specified by the Salary scheme, and this is multiplied by the days worked (which is also calculated using the per_diem_basis). This ensures consistency even when the length of a month differs.

This is how the pay item operates for different pay run types:

Pay run behaviour¶
Behaviour	Scheduled	Custom	On-demand
End date for which salary is due.	End of pay period.	Actual_t.	Actual_t.
“Paid till” date.	End of pay period.	Actual_t.	Not set.

Dated Change support¶

Support for dated changes allows Base Salary changes to be entered, and then be applied on an arbitrary date (for example, mid-pay period or back-dated).

Note

In practice, to reduce data entry errors, back-dating is limited to about a year in the past, and future dating to about a month in the future.

The change is invoked by applying the algorithm described below once using the original Base Salary before the effective date, and once using the Next Base Salary to the period after it. (Whole and fractional periods are therefore evaluated for the two separately).

Once the change has been applied, the inputs are automatically updated as follows:

Base Salary is set using Next Base Salary
Next Base Salary is cleared
Next Effective Date is cleared

Absences¶

When the Absence days input indicates there are absences to be processed, any current absences are associated with the Base Salary or Next Base Salary as appropriate.

However, historical/retrospectively entered absences cannot in general be associated in this way, and the current salary is used.

Algorithm¶

The Pay Period¶

The pay period represents the days over which the employee works. This is specified in Company Setup ‣ Pay Schedules. There are no fixed definitions for pay periods and each company can decide when the pay period formally starts and ends. For monthly paid employees, this could be configured as the first day of the month up to the last day of the month.

Note that this means the pay period is not related to the pay date, and may not start on the pay date.

Per-diem basis for pro-rating¶

Consider that a typical monthly employee will receive 1/12 of their salary each month, which equates to 30.42 calendar days, but actually works for 28 to 31 days depending upon the month. This difference in Paid days vs Actual days is central to the salary scheme, pro-rata and per-diem.

The Base Salary is converted to a daily basis (“per diem”) using a setting in the Salary scheme (see below) for fractional pay periods. There are 4 options to cover all cases: Calendar vs Working days and Annual vs Period (a Period could be monthly weekly 2-Weekly etc.):

Salary Scheme types¶
Scheme per-diem basis	Starter, Leaver or Absence (single period)	In-period or back-dated salary change (multiple periods)
Annual calendar days (365)	Add 1/365 in 1st half of period or Subtract 1/365 in 2nd half	Pro-rata based on calendar days in each period for the date range
Annual working days (260)	Add 1/260 in 1st half of period or Subtract 1/260 in 2nd half	Pro-rata based on working days in each period for the date range
Period calendar days [28..31 monthly]	Pro-rata based on calendar days in the pay period [monthly 1/12 divided by 28..31]	Pro-rata based on calendar days in each period over the date range
Period working days [20..23 monthly]	Pro-rata based on working days in the pay period [monthly 1/12 divided by 20..23]	Pro-rata based on working days in each pay period over the date range

Calendar days counts/uses all days between 2 dates.

Working days counts only the working days as specified on the employee between 2 dates. For employees with 5 working days per week, this evaluates to 5 days x 52 = 260, and so this is sometimes referred to as a 260 option.

Annual means a full-year average designed to give consistent results in different months e.g. 15th February should not differ from 15th March even though the calendar and working days are different (note that this is the same level of consistency as for the whole pay period case). For example, someone who works 5-days per week (Mon-Fri) will use 1/(5*52) or 1/260. For 365 days it will be 1/365 etc. Examples:

£24,000 salary would be £92.31 per diem for 365
£24,000 salary would be £65.75 per diem for Mon-Fri 260

Period (e.g. monthly) means is a precise, but varying per-diem for each month designed to represents the actual day rate received. Regardless of the number of calendar or working days in that month, the period per-diem is based on 1/12 of salary divided by the the Period or Calendar Days in that period. Examples:

£24,000 salary would be £100 per diem for February for 20 working days
£24,000 salary would be £71.43 per diem for February for 28 calendar days
£24,000 salary would be £64.52 per diem for August for 23 working days
£24,000 salary would be £86.96 per diem for August for 31 calendar days

The per-diem is rounded to 2 decimal places.

Example pro-rata payslip messages¶

Messages:

SSP(2024-04-03): No qualifying PIW for 2024-04-03..2024-04-04
SSP(2024-04-27): Qualifies based on 2024-04-27 AWE of 277.50
11 SSP days paid
Salary absence: 14.00 exceeds 13.00 salary days
Salary from 2024-04-01 changed to 9391.20:
- Old Salary (2024-04-01..2024-04-30): 776.10 -4.0 days @ 64.67, absent 4.000
+ New Salary (2024-04-01..2024-04-30): 782.60 -4.0 days @ 65.22, absent 4.000
+ New Salary (2024-05-01..2024-05-31): +1.0 days @ 60.20, absent 12.000

Example pro-rata payslip messages¶
Payslip message	Explanation
SSP (2)	The 1st SSP did not qualify, although the 2nd did.
11 SSP days paid	In total 11 SSP days look paid.
Salary absence: 14.00 exceeds 13.00 salary days	In in this pay period SSP would have suppressed salary by 14 days (11 SSP days +3 waiting days). However, there were only 13 salary days available.
Salary from 2024-04-01 changed to 9391.20:	The salary was confirmed as changed to a new value on a retrospective date.
Old Salary (2024-04-01..2024-04-30): 776.10 -4.0 days @ 64.67, absent 4.000	The old salary for April was 77.10, however they were 4 days absent and so this amount is subtracted
New Salary (2024-04-01..2024-04-30): 782.60 -4.0 days @ 65.22, absent 4.000	This is the new salary for the same period in April
New Salary (2024-05-01..2024-05-31): +1.0 days @ 60.20, absent 12.000	This is the new salary for May noting that there were 12 absent days, and therefore only 1 payable day

Start date¶

The start date is:

The pay period start by default.
OR the employment start date for a starter. This may be later if the employee has started later, or earlier if the employment started after the previous pay date.

End date¶

The end date is:

The pay period end by default.
OR actual_t for a custom/on-demand run (defaults to today for the API case).
OR the employment end date for a leaver.

Calculation¶

First, the gross pay for whole period(s) from start date to end date is calculated, then any fractional period is pro-rated on a per-diem basis. The number of days between these two dates depends on the salary scheme and the employee working days. Examples:

15th March would be 15 if using a 365 scheme.
15th March would be 11 if using a working days scheme for 5 working days a week.

The pro-rata gross salary for the fractional period is this number of days multiplied by the per-diem. Examples for 15th of the month:

£24,000 salary would be £1015.41 365
£24,000 salary would be £986.25 for Mon-Fri 260

The difference between the two arises due to the calculation of the numerator and denominator and what exact proportion each represents. Normally one scheme will be used and the differences are academic.

Pay run approval dead-period¶

When a pay run is approved the system moves to the next pay period. For example approval on the 25th of March would move the pay run to the next month of April. This means that an API call with a date anywhere between the 26th and 31st of March will result in zero Gross pay as the actual_t date is before the pay period of 1st to 30th April.

Universal SalaryScheme¶

SalaryScheme has the following scheme settings:

clazz:

Determines the remaining settings.

per_diem_basis:

Convert annual amount to a per_diem based on:

365_days
working_days
period calendar days
period working days

annual_hours:

The number of annual hours worked each year.

pro_rate:

When to pro-rate:

All uses
Start and end dates only

days_per_year:

The number of days in a year:

365 days
365.25 days

weeks_per_year:

The number of weeks in a year:

52 weeks
52.14 weeks
52.17857 weeks

The scheme must be selected from:

paiyroll.pay.Universal.salary.SalaryScheme

Example:

{
    "clazz": "paiyroll.pay.Universal.salary.SalaryScheme",
    "per_diem_basis": "working_days"
}

Timesheet Schemes¶

Timesheets provide for reporting of pay by time-of-attendance and by piece:

Time-of-attendance-based timesheets support traditional clock-in-clock-out style recording of hours, days or weeks.
Piece-based timesheets support daily or weekly reporting of piece rate work. They can also be used for recording hours when the actual clock-in-clock-out times are not needed.

All timesheet schemes allow for upto 3 rates of pay, each defined by a setting describing nests as follows:

normal:: Non-overtime rate nest.
weekend:: Overtime rate nest for weekends.
holiday:: Overtime rate nest for holidays.

Each nest describes a span of time for which a percentage applies:

(start, end, percentage, [nest...])

and includes further nests which (recursively) divide a row in the timesheet into periods of time:

start:: When the period begins.
end:: When the period ends.
percentage:: Multipler of pay rate. Default is 100.
nest:: A list of periods whose start and end are nested within the current period.

For each period, the pay rate is multiplied by the percentage. For example:

{
    "normal": [
        #
        # 2.0x normal pay from 00:00-24:00.
        #
        {"percent": 200, "start": 0, "end": 24, "nests": [
            #
            # 1.5x normal pay from 06:00-21:00.
            #
            {"percent": 150, "start": 6, "end": 21, "nests": [
                #
                # Percent defaults to 100 for 09:00-12:00 and 13:00-18:00.
                #
                {"start": 9, "end": 12},
                {"start": 13, "end": 18},
            ]},
        ]},
    ],
    "weekend": None,        # Same as normal.
    "holiday": [
        {"percent": 200},   # 2.0x normal pay.
    ],
}

See the individual schemes for details.

Universal Time-of-Attendance-based timesheets¶

Each worker’s pay item specifies:

Timesheet expired:: Need a new timesheet.
Work rate:: The rate of pay for normal work.
Holiday rate:: The rate for holiday pay.
Scheme:: Timesheet scheme definition.

To create a time-of-attendance-based Timesheet scheme, create a Pay Definition based on the required Pay Template for Hourly, Daily or Weekly schemes. The scheme of an attendance-based Timesheet schemes determines all the other settings.

Universal HourlyScheme¶

HourlyScheme has the following scheme settings:

clazz:

Determines the remaining settings.

period:

The timesheet period (w1, m1 etc).

overtime:

Overtime rates

moments_per_unit:

Each unit is 1 hour which is divided to configure the desired granularity:

1 for 60 minute
2 for 30 minute
4 for 15 minute
6 for 10 minute
12 for 5 minute
60 for 1 minute

The scheme must be selected from:

paiyroll.pay.Universal.timesheet.time.HourlyScheme

Universal DailyScheme¶

DailyScheme has the following scheme settings:

clazz:

Determines the remaining settings.

period:

The timesheet period (w1, m1 etc).

overtime:

Overtime rates

moments_per_unit:

Each unit is 1 day which is divided to configure the desired granularity:

1 (day)
2 (half-day)

hours_per_day:

Hours per day in the workers contract.

The scheme must be selected from:

paiyroll.pay.Universal.timesheet.time.DailyScheme

Universal WeeklyScheme¶

WeeklyScheme has the following scheme settings:

clazz:: Determines the remaining settings.
period:: The timesheet period (w1, m1 etc).
overtime:: Overtime rates
moments_per_unit:: Each unit is 1 week. This cannot be divided so this must be set to 1.
hours_per_week:: Hours per week in the workers contract.

The scheme must be selected from:

paiyroll.pay.Universal.timesheet.time.WeeklyScheme

Workflows¶

The pay item requires a Workflow Definition based on paiyroll.flows.timesheet.TimesheetFlow.

Universal Piece-based timesheets¶

Each worker’s pay item specifies:

Timesheet expired:: Need a new timesheet.
Piece rate 1:: The rates of pay for each piece. Only rates will be used/displayed.
Piece rate 2:: See rate1.
Piece rate 3:: See rate1.
Scheme:: Timesheet scheme definition.

To create a piece-based Timesheet scheme, create a Pay Definition based on the required Pay Template for Daily or Weekly schemes. All the piece-based Timesheet schemes support upto 3 piece-based rates. The scheme of a piece-based Timesheet schemes determines all the other settings.

Universal DailyScheme¶

DailyScheme has the following scheme settings:

clazz:: Determines the remaining settings.
period:: The timesheet period (w1, m1 etc).
rates:: How many of rate1…rateN are in use?
places:: The granularity with which pieces are counted, as powers of 10, from -2 to +2.
average_rate:: Benchmark average rate of pieces completed per hour.
overtime:: Overtime rates

The scheme must be selected from:

paiyroll.pay.Universal.timesheet.piece.DailyScheme

Example:

{
    "clazz": "paiyroll.pay.Universal.timesheet.piece.DailyScheme",
    "period": "w1",
    "rates": 1,
    "normal": [{"percent": 100}],
    "weekend": null,
    "holiday": [{"percent": 200}]
}

Universal WeeklyScheme¶

WeeklyScheme has the following scheme settings:

clazz:: Determines the remaining settings.
period:: The timesheet period (w1, m1 etc).
rates:: How many of rate1…rateN are in use?
places:: The granularity with which pieces are counted, as powers of 10, from -2 to +2.
average_rate:: Benchmark average rate of pieces completed per hour.
overtime:: Overtime rates

The scheme must be selected from:

paiyroll.pay.Universal.timesheet.piece.WeeklyScheme

Workflows¶

The pay item requires a Workflow Definition based on paiyroll.flows.timesheet.TimesheetFlow.

rolling_limit %	Equivalent absence
3	2 or fewer days in 13 weeks
2	3 or fewer days in 26 weeks
1	3 or fewer days in 52 weeks