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_foundfor another company's payslip.POST /payslips/{payslipId}/link:201with{ url, expiresAt }, valid about five minutes, returned once withCache-Control: no-store.404 not_foundwhen 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.
Handling links
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 |