Copy page

Guides

Monthly payroll cycles

A payroll cycle covers one tenant and one monthly period. The V1 journey supports one company officer per tenant and the current month or M-1 for writes. Older revisions remain readable. Approval and finalization do not initiate payment or file a DSN. The new calculate, operation, abandon and document routes are currently closed by MANAGED_PAYROLL_V1_ENABLED and return 404 payroll_journey_unavailable until Verso explicitly activates them. Existing cycle, variables, preview and approval routes remain served.

Use the Gateway paths below, prefixed with /partners/{partnerId}/tenants/{tenantId}/payroll-cycles. The period uses YYYY-MM. The API key must belong to the partner and tenant; a different partner or tenant cannot read or change the cycle. Keep each response's ETag for the next write's If-Match header.

Enter and calculate

1. PUT /{period} creates the cycle or returns its current revision.
2. PUT /{period}/variables with If-Match sends remuneration in euros (including zero) and dateDeVersement as an explicitly confirmed YYYY-MM-DD payment date. OpsService records the write intent before sending it to PayrollEngine; the engine decides whether the date and payroll input are admissible.
3. POST /{period}/calculate with If-Match and a stable Idempotency-Key returns 202 Accepted and an operation URL. This starts one persisted real payroll calculation, not a forecast. Repeating the same key for the same request returns the same operation. Poll GET /{period}/operations/{operationId} until completed, failed or reconcile_required; 202 does not mean the calculation succeeded.
4. GET /{period} is the source of truth. A completed calculation exposes a candidate with id, job and result-set IDs, and a result for that exact candidate. The result contains outcome, warnings, blockers and persons (one person in V1). Each person has gross, employee and employer contributions, net deductions, net before tax, net social, PAS, net payable, employer cost and the native wage-type details. These amounts are copied from the engine's result set; missing or ambiguous native values are null. In FR.Salaire 2026, the classic bulletin builds net before tax from native net payable (WT 7025) plus native PAS (WT 5100, mirrored by WT 7005). Verso requires the two PAS values to agree before exposing this amount. Net social is the separate WT 6000. The result is absent until an exact candidate is ready.

The cycle states are collecting, preview_ready, approved, finalized, filed, accepted and correction_required. The operation has its own status and phase, separate from the cycle state. A failed or reconcile_required operation exposes a blocker code. When the effect of a lost engine response cannot be identified uniquely, OpsService requires operator reconciliation and never sends the native command again blindly. A competing calculation or decision returns 409 payroll_operation_collision with the active operation ID.

Approve the exact result

After reviewing result and the candidate.id, send POST /{period}/approval with the latest If-Match and body {"approvalKey":"stable-key","candidateId":"the-reviewed-id"}. The response is 202 with an operation URL. Approval is bound to that candidate, input generation, exact engine job and result set. The worker finalizes that same job without recalculating. Poll the operation and then read the cycle; finalized is distinct from approved and from filing.

If the variables or relevant tenant inputs change, the old candidate becomes invalid and a new calculation and review are required. An old ETag yields 412; an old candidate yields a conflict. Before approval, including after an input has invalidated a draft, POST /{period}/abandon with If-Match and body {"candidateId":"...","idempotencyKey":"stable-key"} explicitly abandons the exact draft. After finalization, a change creates a new revision for correction; the prior result and documents are not overwritten. The first input on an empty M-1 cycle remains revision 1; changing an existing input after cutoff or approval creates the next revision. When a prior month is corrected while the following month is still open, each input remains scoped to its own month. Resending the following month's unchanged variables is an idempotent read of its existing write. A calculation can be requested immediately after a confirmed write; Ops chooses an engine evaluation instant that includes that write.

For a legacy simulation or draft that has no Ops candidate, use POST /{period}/drafts/{jobId}/abort with the latest If-Match and a stable UUID requestKey. Supply reasonCode as simulation_discarded, draft_replaced or operator_recovery. This queues an audited operation for that exact native Draft; poll the returned operation URL until completed before requesting a fresh calculation. A repeated key returns the same operation. An approved, foreign, non-Draft or candidate-owned job is refused. An ambiguous response keeps the payroll reserved until Ops verifies native history. This route is off by default (Ops__DraftAbortEnabled=false) until Verso completes its database, writer and clock checks. Older drafts outside M/M−1 require the authenticated Ops recovery path; the partner window is unchanged.

POST /{period}/preview remains a compatibility readiness check for legacy cycles. A managed candidate uses calculate plus GET; preview cannot select a different native result. Legacy approval without candidateId remains confined to cycles with no managed candidate. New integrations should always send candidateId.

For an existing legacy cycle, read its ETag, call POST /{period}/preview with If-Match, and check state=preview_ready, preview.pdfProof=ready, empty preview.blockers, and the exact payrunJobId and resultSetId. Then call GET /{period}/payslip to obtain a temporary private PDF URL. Its response includes the beneficiary, period, revision, job, result set and checksum. Download the URL and compare the PDF with that identity. documentStatus=preview means the partner has not approved it; approved_preview means the same legacy preview was approved, but it is not a managed final document. If the PDF is not ready, the API returns 409 payslip_not_ready with cycleState, the last preview including its blockers, and a nextAction (set_cycle_variables, prepare_preview, wait_for_payrun, resolve_preview_blockers or contact_verso when rendering is disabled or failed). Do not attempt to open a missing URL. A genuine unknown cycle still returns 404.

Documents

Generate or retry a document with POST /{period}/revisions/{revision}/candidates/{candidateId}/documents/{variant} and read it with GET on the same path. variant is draft or final. The draft is optional and visibly marked BROUILLON — À VALIDER. Approval does not require it. The final document is available only after finalization; it has a different identity and no draft mark. In sandbox it carries TEST — SANS VALEUR. Document generation failure can be retried without recalculating or refinalizing payroll.

Each document response has its own status, checksum, retention deadline and a temporary private read URL when ready. Call GET again to renew an expired URL. The document retains its identity and storage version independently of the URL. Sandbox documents are retained for 180 days; staging and preproduction use configured retention periods, and production can be configured without automatic expiration. Once retention expires, PDF and manifest versions and document metadata are purged; reads and generation return 410 document_retention_expired. Earlier revisions remain addressable by their original revision and candidate IDs during retention.

Limits and recovery

GET and operation polling remain authoritative even if a client misses a response. When Verso has configured an optional HTTPS destination for your partner and environment, it sends payroll_cycle.updated after useful changes: calculation ready/failed/requiring reconciliation, operator reconciliation resolved, candidate invalidation or abandonment, finalization, and document ready/failed. There is no subscription URL in a calculation request. The signal contains references only, so always re-read the cycle or operation with your API key. Notifications can arrive twice or out of order. If no destination is configured, polling alone provides the complete journey.

For example, a receiver may see:

Code
{"eventId":"msg_…","schemaVersion":"1","type":"payroll_cycle.updated","occurredAt":"2026-09-27T12:00:00Z","data":{"environment":"sandbox","partnerId":"42","tenantId":"7","period":"2026-09","revision":1,"change":"calculation.ready","candidateId":"…","operationId":123,"documentId":null,"resource":"/partners/42/tenants/7/payroll-cycles/2026-09"}}

The sender includes webhook-id (stable event ID), webhook-timestamp (Unix seconds for this attempt) and webhook-signature (v1, plus base64 HMAC-SHA256). Verify the signature over the raw bytes webhook-id.webhook-timestamp.body, reject stale timestamps, persist the ID before returning 2xx, then call the authenticated GET. During secret rotation the signature header can contain two space-separated signatures. See the Standard Webhooks specification. Verso retries transient non-2xx or lost responses with jittered backoff for up to 24 hours, at most one hour between attempts. After exhaustion, Verso Ops can audit and replay the same event ID and body; the attempt timestamp and signature change. An unavailable webhook does not cancel or repeat payroll. HTTP 410 suspends the delivery for operator investigation.

A variable write that may have succeeded downstream is exposed as 409 variable_write_reconciliation_required, with variableWrite.id, status and reconciliationRequired: true on the cycle. Do not retry that write until Ops has reconciled the frozen intent against engine history. The same principle applies to ambiguous calculation and finalization effects.

The V1 write window is M/M-1. A later managed month must use only earlier finalized results: prior_month_not_finalized refuses a calculation started too soon. If a later month is already finalized, R1 returns later_finalized_month_requires_operator_replay for an earlier correction. Verso Ops must inspect the downstream jobs and explicitly replay their correction revisions in order; no finalized month is changed automatically. The internal operator route checks the exact finalized job/result list and opens new, empty revisions; each month needs a fresh input, calculation and approval backed by recorded partner consent. It is disabled by default and does not expand the partner M/M−1 window. Inactive or offboarded tenants cannot start partner payroll mutations. The native write guard remains active for an existing managed payroll even when the managed journey flag is closed; native writes require the Ops policy lookup and fail closed if that lookup is unavailable. Verso's legal control and DSN transmission remain separate Ops workflows.