Payslips and documents

Payslips exist once a pay run is published or lodged. Your page lists them and opens them through short-lived links; the documents themselves never pass through your servers.

Sessions: an employer session with payruns:read to list and documents:read to open; an employee session with self:payslips for a person's own payslips.

Employer view

  • GET /payruns/{payrunId}/payslips: one summary per employee of that run (id, employeeId, period, paymentDate, documentAvailable); empty before the engine's publish. No amounts in this slice.
  • GET /payslips/{payslipId}: one summary. 404 not_found for another company's payslip.
  • POST /payslips/{payslipId}/link: 201 with { url, expiresAt }, valid about five minutes, returned once with Cache-Control: no-store. 404 not_found when the payslip has no document yet.

The PayrunHistory component (with detail: 'inline') and the RunPayroll component after lodgement show the payslips with an Open payslip action that mints the link and opens it in a new tab.

Employee view

GET /self/payslips, GET /self/payslips/{payslipId} and POST /self/payslips/{payslipId}/link do the same for the session's employee only. The SelfPayslips component renders them. An employee session comes from an invitation exchange or from a session you mint with sessionType: employee and the person's employeeId.

Payment file

The pay run's bank file (ABA) is a document too: POST /payruns/{payrunId}/payment-file/link for an approved or later run, with the preconditions described in Run payroll.

The URL is a bearer credential for the document. Open it in a new tab or hand it to the browser immediately; do not store it, log it, put it in your own database or send it in an e-mail. When it has expired, mint another one; minting is cheap and each mint is audited by payslip id, never by URL. Headless browsers download the PDF rather than render it.

Events

Page events payslip.available (after publish) and payment_file.available (after approval with a valid payer account) tell your page a document can now be opened; document.opened fires when a link was minted, so your journey tracking sees it in both shells.

What you should see

After a lodged run, GET /payruns/{id}/payslips lists every employee with documentAvailable: true; a link opens a PDF payslip; GET /self/payslips on an employee session for one of them lists their own payslip and no one else's.

Errors you may see

Status and code Meaning Next action
403 scope_missing documents:read (or self:payslips) not in the session mint with the scope
404 not_found unknown, another company's, or no document yet wait for publish; check the id