Compatibility Payroll and Salary API

Summary

Fifteen compatibility operations preserve Payroll, Salary, and read-only statutory contracts during gateway cutover.

Audience

Frontend and backend developers, QA and support engineers, architects, security reviewers, and implementation partners.

Reference Content

Authentication: bearer context is expected for business APIs; service-local enforcement Requires confirmation. Authorization: no endpoint-specific Payroll Service role policy is confirmed. Maturity: Compatibility / Transitional.

Operation	Method and public route	Purpose	Authentication	Tenant context	Request type	Response type	Success	Maturity	Source path
Payroll status	GET /api/payroll/status	Return period/run capability flags.	Bearer expected by the compatibility contract; downstream enforcement Requires confirmation	Forwarded tenant context expected; no tenant query parameter	Query parameters	Anonymous Payroll status object	200	Compatibility	microservices/src/payroll-service/Api/PayrollCompatEndpoints.cs
Payroll run	GET /api/payroll/run	Return a period run with compatibility details.	Bearer expected by the compatibility contract; downstream enforcement Requires confirmation	Forwarded tenant context expected; no tenant query parameter	Query parameters	Anonymous compatibility run object	200	Compatibility	microservices/src/payroll-service/Api/PayrollCompatEndpoints.cs
Calculate Payroll	POST /api/payroll/calculate	Calculate a period through the native engine and return compatibility shape.	Bearer expected by the compatibility contract; downstream enforcement Requires confirmation	Forwarded tenant context expected; no tenant query parameter	MonthYearCompatRequest	Anonymous compatibility run object	200	Compatibility	microservices/src/payroll-service/Api/PayrollCompatEndpoints.cs
Freeze Payroll	POST /api/payroll/freeze	Calculate when needed and freeze the current period run.	Bearer expected by the compatibility contract; downstream enforcement Requires confirmation	Forwarded tenant context expected; no tenant query parameter	MonthYearCompatRequest	Anonymous compatibility run object	200	Compatibility	microservices/src/payroll-service/Api/PayrollCompatEndpoints.cs
Unfreeze Payroll	POST /api/payroll/unfreeze	Unfreeze the current Frozen period run through native lifecycle.	Bearer expected by the compatibility contract; downstream enforcement Requires confirmation	Forwarded tenant context expected; no tenant query parameter	MonthYearCompatRequest	Anonymous compatibility run object	200	Compatibility	microservices/src/payroll-service/Api/PayrollCompatEndpoints.cs
Payroll audit	GET /api/payroll/audit	Return compatibility run audit history.	Bearer expected by the compatibility contract; downstream enforcement Requires confirmation	Forwarded tenant context expected; no tenant query parameter	Query parameters	Anonymous compatibility audit array	200	Compatibility	microservices/src/payroll-service/Api/PayrollCompatEndpoints.cs
Payroll period lock	GET /api/payroll/period-lock	Return whether a period is Frozen.	Bearer expected by the compatibility contract; downstream enforcement Requires confirmation	Forwarded tenant context expected; no tenant query parameter	Query parameters	Anonymous {isFrozen} object	200	Compatibility	microservices/src/payroll-service/Api/PayrollCompatEndpoints.cs
Salary status	GET /api/salary/status	Return compatibility salary-period capability flags.	Bearer expected by the compatibility contract; downstream enforcement Requires confirmation	Forwarded tenant context expected; no tenant query parameter	Query parameters	Anonymous salary status object	200	Compatibility	microservices/src/payroll-service/Api/PayrollCompatEndpoints.cs
Frozen salary rows	GET /api/salary/frozen	List Frozen compatibility salary rows.	Bearer expected by the compatibility contract; downstream enforcement Requires confirmation	Forwarded tenant context expected; no tenant query parameter	Query parameters	Anonymous salary row array	200	Compatibility	microservices/src/payroll-service/Api/PayrollCompatEndpoints.cs
Approved Expense inputs	GET /api/salary/approved-expenses	Return approved reimbursement totals for calculation clients.	Bearer expected by the compatibility contract; downstream enforcement Requires confirmation	Forwarded tenant context expected; no tenant query parameter	Query parameters	Anonymous employee/amount array	200	Compatibility	microservices/src/payroll-service/Api/PayrollCompatEndpoints.cs
Calculate employee salary preview	GET /api/salary/calculate/{laborId:int}	Return one calculated net-result field for an employee.	Bearer expected by the compatibility contract; downstream enforcement Requires confirmation	Forwarded tenant context expected; no tenant query parameter	Route and query parameters	Anonymous {salary} object	200	Compatibility	microservices/src/payroll-service/Api/PayrollCompatEndpoints.cs
Save salary row	POST /api/salary/save-row	Upsert one compatibility salary row.	Bearer expected by the compatibility contract; downstream enforcement Requires confirmation	Forwarded tenant context expected; no tenant query parameter	SalaryRowCompatRequest	Anonymous compatibility salary row	200	Compatibility	microservices/src/payroll-service/Api/PayrollCompatEndpoints.cs
Freeze salary rows	POST /api/salary/freeze	Persist supplied compatibility salary rows and freeze the run.	Bearer expected by the compatibility contract; downstream enforcement Requires confirmation	Forwarded tenant context expected; no tenant query parameter	SalaryFreezeCompatRequest	Anonymous compatibility salary row array	200	Compatibility	microservices/src/payroll-service/Api/PayrollCompatEndpoints.cs
Unfreeze salary rows	POST /api/salary/unfreeze	Return Frozen salary rows to editable compatibility state.	Bearer expected by the compatibility contract; downstream enforcement Requires confirmation	Forwarded tenant context expected; no tenant query parameter	MonthYearCompatRequest	Anonymous message/period/row-count object	200	Compatibility	microservices/src/payroll-service/Api/PayrollCompatEndpoints.cs
Read statutory settings	GET /api/hr-operations/statutory-settings	Return read-only compatibility statutory-setting metadata.	Bearer expected by the compatibility contract; downstream enforcement Requires confirmation	Forwarded tenant context expected; no tenant query parameter	None	Anonymous setting array	200	Compatibility	microservices/src/payroll-service/Api/PayrollCompatEndpoints.cs

Payroll status

• API family / maturity: Compatibility Payroll and Salary API; Compatibility
• Authentication / authorization: Bearer expected by the compatibility contract; downstream enforcement Requires confirmation. No endpoint-specific role policy is confirmed.
• Tenant context: Forwarded tenant context expected; no tenant query parameter.
• Route parameters: None.
• Query parameters: Required month, year.
• Request body / type: None; Query parameters.
• Validation: Only checks stated in the error mapping below are confirmed; model-binding failures are framework behavior and not specified as a stable contract.
• Response body / type: Anonymous Payroll status object.
• Success / error responses: 200; No endpoint-specific error response is mapped.
• Business behavior: Return period/run capability flags.
• State and input implications: Read-only. No input projection changes.
• Audit and event implications: No audit side effect confirmed. No event produced.
• Compatibility notes: Monolith-shaped compatibility contract.
• Safe example: GET /api/payroll/status?month=7&year=2026 → 200 status/capability metadata
• Example error: No stable endpoint-specific error example is confirmed.

Payroll run

• API family / maturity: Compatibility Payroll and Salary API; Compatibility
• Authentication / authorization: Bearer expected by the compatibility contract; downstream enforcement Requires confirmation. No endpoint-specific role policy is confirmed.
• Tenant context: Forwarded tenant context expected; no tenant query parameter.
• Route parameters: None.
• Query parameters: Required month, year.
• Request body / type: None; Query parameters.
• Validation: Only checks stated in the error mapping below are confirmed; model-binding failures are framework behavior and not specified as a stable contract.
• Response body / type: Anonymous compatibility run object.
• Success / error responses: 200; 404 raw text when no run exists.
• Business behavior: Return a period run with compatibility details.
• State and input implications: Read-only. No input projection changes.
• Audit and event implications: No audit side effect confirmed. No event produced.
• Compatibility notes: Monolith-shaped compatibility contract.
• Safe example: GET /api/payroll/run?month=7&year=2026 → 200 run metadata; absent → 404 raw text
• Example error: "Request could not be completed." (illustrative raw compatibility wording)

Calculate Payroll

• API family / maturity: Compatibility Payroll and Salary API; Compatibility
• Authentication / authorization: Bearer expected by the compatibility contract; downstream enforcement Requires confirmation. No endpoint-specific role policy is confirmed.
• Tenant context: Forwarded tenant context expected; no tenant query parameter.
• Route parameters: None.
• Query parameters: None.
• Request body / type: month, year; MonthYearCompatRequest.
• Validation: Only checks stated in the error mapping below are confirmed; model-binding failures are framework behavior and not specified as a stable contract.
• Response body / type: Anonymous compatibility run object.
• Success / error responses: 200; 400 raw text for handled argument/domain failure.
• Business behavior: Calculate a period through the native engine and return compatibility shape.
• State and input implications: Creates/recalculates an editable run. Uses native calculation input boundaries.
• Audit and event implications: Native calculation audit/timeline applies. Native Payroll-calculated event is staged.
• Compatibility notes: Monolith-shaped compatibility contract.
• Safe example: POST /api/payroll/calculate with {"month":7,"year":2026} → 200 run metadata; handled failure → 400 raw text
• Example error: "Request could not be completed." (illustrative raw compatibility wording)

Freeze Payroll

• API family / maturity: Compatibility Payroll and Salary API; Compatibility
• Authentication / authorization: Bearer expected by the compatibility contract; downstream enforcement Requires confirmation. No endpoint-specific role policy is confirmed.
• Tenant context: Forwarded tenant context expected; no tenant query parameter.
• Route parameters: None.
• Query parameters: None.
• Request body / type: month, year; MonthYearCompatRequest.
• Validation: Only checks stated in the error mapping below are confirmed; model-binding failures are framework behavior and not specified as a stable contract.
• Response body / type: Anonymous compatibility run object.
• Success / error responses: 200; 400 raw text for handled failure.
• Business behavior: Calculate when needed and freeze the current period run.
• State and input implications: Uses native Frozen lifecycle. Applies native advance recovery.
• Audit and event implications: Native freeze audit/timeline applies. Native Payroll-frozen event is staged.
• Compatibility notes: Monolith-shaped compatibility contract.
• Safe example: POST /api/payroll/freeze with period body → 200 with status:"Frozen"
• Example error: "Request could not be completed." (illustrative raw compatibility wording)

Unfreeze Payroll

• API family / maturity: Compatibility Payroll and Salary API; Compatibility
• Authentication / authorization: Bearer expected by the compatibility contract; downstream enforcement Requires confirmation. No endpoint-specific role policy is confirmed.
• Tenant context: Forwarded tenant context expected; no tenant query parameter.
• Route parameters: None.
• Query parameters: None.
• Request body / type: month, year; MonthYearCompatRequest.
• Validation: Only checks stated in the error mapping below are confirmed; model-binding failures are framework behavior and not specified as a stable contract.
• Response body / type: Anonymous compatibility run object.
• Success / error responses: 200; 400 raw text for handled failure.
• Business behavior: Unfreeze the current Frozen period run through native lifecycle.
• State and input implications: Uses native Unfrozen lifecycle. Uses native recovery reversal.
• Audit and event implications: Native unfreeze audit/timeline applies. Native Payroll-unfrozen event is staged.
• Compatibility notes: Monolith-shaped compatibility contract.
• Safe example: POST /api/payroll/unfreeze with period body → 200 with status:"Unfrozen"
• Example error: "Request could not be completed." (illustrative raw compatibility wording)

Payroll audit

• API family / maturity: Compatibility Payroll and Salary API; Compatibility
• Authentication / authorization: Bearer expected by the compatibility contract; downstream enforcement Requires confirmation. No endpoint-specific role policy is confirmed.
• Tenant context: Forwarded tenant context expected; no tenant query parameter.
• Route parameters: None.
• Query parameters: Required month, year.
• Request body / type: None; Query parameters.
• Validation: Only checks stated in the error mapping below are confirmed; model-binding failures are framework behavior and not specified as a stable contract.
• Response body / type: Anonymous compatibility audit array.
• Success / error responses: 200; No endpoint-specific error response is mapped.
• Business behavior: Return compatibility run audit history.
• State and input implications: Read-only. No input projection changes.
• Audit and event implications: No audit side effect confirmed. No event produced.
• Compatibility notes: Monolith-shaped compatibility contract.
• Safe example: GET /api/payroll/audit?month=7&year=2026 → 200 []
• Example error: No stable endpoint-specific error example is confirmed.

Payroll period lock

• API family / maturity: Compatibility Payroll and Salary API; Compatibility
• Authentication / authorization: Bearer expected by the compatibility contract; downstream enforcement Requires confirmation. No endpoint-specific role policy is confirmed.
• Tenant context: Forwarded tenant context expected; no tenant query parameter.
• Route parameters: None.
• Query parameters: Required laborId, month, year.
• Request body / type: None; Query parameters.
• Validation: Only checks stated in the error mapping below are confirmed; model-binding failures are framework behavior and not specified as a stable contract.
• Response body / type: Anonymous {isFrozen} object.
• Success / error responses: 200; No endpoint-specific error response is mapped.
• Business behavior: Return whether a period is Frozen.
• State and input implications: Read-only. No input projection changes.
• Audit and event implications: No audit side effect confirmed. No event produced.
• Compatibility notes: Monolith-shaped compatibility contract.
• Safe example: GET /api/payroll/period-lock?laborId={employeeRef}&month=7&year=2026 → 200 {"isFrozen":false}
• Example error: No stable endpoint-specific error example is confirmed.

Salary status

• API family / maturity: Compatibility Payroll and Salary API; Compatibility
• Authentication / authorization: Bearer expected by the compatibility contract; downstream enforcement Requires confirmation. No endpoint-specific role policy is confirmed.
• Tenant context: Forwarded tenant context expected; no tenant query parameter.
• Route parameters: None.
• Query parameters: Required month, year.
• Request body / type: None; Query parameters.
• Validation: Only checks stated in the error mapping below are confirmed; model-binding failures are framework behavior and not specified as a stable contract.
• Response body / type: Anonymous salary status object.
• Success / error responses: 200; No endpoint-specific error response is mapped.
• Business behavior: Return compatibility salary-period capability flags.
• State and input implications: Read-only. No input projection changes.
• Audit and event implications: No audit side effect confirmed. No event produced.
• Compatibility notes: Monolith-shaped compatibility contract.
• Safe example: GET /api/salary/status?month=7&year=2026 → 200 status/capability metadata
• Example error: No stable endpoint-specific error example is confirmed.

Frozen salary rows

• API family / maturity: Compatibility Payroll and Salary API; Compatibility
• Authentication / authorization: Bearer expected by the compatibility contract; downstream enforcement Requires confirmation. No endpoint-specific role policy is confirmed.
• Tenant context: Forwarded tenant context expected; no tenant query parameter.
• Route parameters: None.
• Query parameters: Required month, year.
• Request body / type: None; Query parameters.
• Validation: Only checks stated in the error mapping below are confirmed; model-binding failures are framework behavior and not specified as a stable contract.
• Response body / type: Anonymous salary row array.
• Success / error responses: 200; No endpoint-specific error response is mapped.
• Business behavior: List Frozen compatibility salary rows.
• State and input implications: Read-only. No input projection changes.
• Audit and event implications: No audit side effect confirmed. No event produced.
• Compatibility notes: Monolith-shaped compatibility contract.
• Safe example: GET /api/salary/frozen?month=7&year=2026 → 200 []
• Example error: No stable endpoint-specific error example is confirmed.

Approved Expense inputs

• API family / maturity: Compatibility Payroll and Salary API; Compatibility
• Authentication / authorization: Bearer expected by the compatibility contract; downstream enforcement Requires confirmation. No endpoint-specific role policy is confirmed.
• Tenant context: Forwarded tenant context expected; no tenant query parameter.
• Route parameters: None.
• Query parameters: Required month, year.
• Request body / type: None; Query parameters.
• Validation: Only checks stated in the error mapping below are confirmed; model-binding failures are framework behavior and not specified as a stable contract.
• Response body / type: Anonymous employee/amount array.
• Success / error responses: 200; No endpoint-specific error response is mapped.
• Business behavior: Return approved reimbursement totals for calculation clients.
• State and input implications: Read-only. Reads Payroll Expense projection; no Expense mutation.
• Audit and event implications: No audit side effect confirmed. No event produced.
• Compatibility notes: Monolith-shaped compatibility contract.
• Safe example: GET /api/salary/approved-expenses?month=7&year=2026 → 200 []
• Example error: No stable endpoint-specific error example is confirmed.

Calculate employee salary preview

• API family / maturity: Compatibility Payroll and Salary API; Compatibility
• Authentication / authorization: Bearer expected by the compatibility contract; downstream enforcement Requires confirmation. No endpoint-specific role policy is confirmed.
• Tenant context: Forwarded tenant context expected; no tenant query parameter.
• Route parameters: Required integer employee reference.
• Query parameters: Required month, year.
• Request body / type: None; Route and query parameters.
• Validation: Only checks stated in the error mapping below are confirmed; model-binding failures are framework behavior and not specified as a stable contract.
• Response body / type: Anonymous {salary} object.
• Success / error responses: 200; No endpoint-specific error response is mapped.
• Business behavior: Return one calculated net-result field for an employee.
• State and input implications: May calculate/recalculate the whole period when no Frozen run exists. Uses native calculation inputs.
• Audit and event implications: Native calculation evidence applies when recalculation occurs. Native calculated event applies when recalculation occurs.
• Compatibility notes: Monolith-shaped compatibility contract.
• Safe example: GET /api/salary/calculate/{laborId:int}?month=7&year=2026 → 200 financial result field; value omitted
• Example error: No stable endpoint-specific error example is confirmed.

Save salary row

• API family / maturity: Compatibility Payroll and Salary API; Compatibility
• Authentication / authorization: Bearer expected by the compatibility contract; downstream enforcement Requires confirmation. No endpoint-specific role policy is confirmed.
• Tenant context: Forwarded tenant context expected; no tenant query parameter.
• Route parameters: None.
• Query parameters: Required month, year.
• Request body / type: laborId, base/overtime/component fields, optional breakdown, advance/other deductions, final result; SalaryRowCompatRequest.
• Validation: Only checks stated in the error mapping below are confirmed; model-binding failures are framework behavior and not specified as a stable contract.
• Response body / type: Anonymous compatibility salary row.
• Success / error responses: 200; 400 raw text for future month, Frozen month, invalid employee, or recovery failure.
• Business behavior: Upsert one compatibility salary row.
• State and input implications: Creates/reuses editable run and updates totals. May apply an advance-recovery delta.
• Audit and event implications: No lifecycle audit row added by save-row. No event produced.
• Compatibility notes: Monolith-shaped compatibility contract.
• Safe example: Illustrative request uses {employee reference} and <financial value> placeholders; success → 200 salary row metadata
• Example error: "Request could not be completed." (illustrative raw compatibility wording)

Freeze salary rows

• API family / maturity: Compatibility Payroll and Salary API; Compatibility
• Authentication / authorization: Bearer expected by the compatibility contract; downstream enforcement Requires confirmation. No endpoint-specific role policy is confirmed.
• Tenant context: Forwarded tenant context expected; no tenant query parameter.
• Route parameters: None.
• Query parameters: None.
• Request body / type: month, year, items (SalaryRowCompatRequest[]); SalaryFreezeCompatRequest.
• Validation: Only checks stated in the error mapping below are confirmed; model-binding failures are framework behavior and not specified as a stable contract.
• Response body / type: Anonymous compatibility salary row array.
• Success / error responses: 200; 400 raw text for future month, duplicate freeze, empty items, invalid employee, or recovery failure.
• Business behavior: Persist supplied compatibility salary rows and freeze the run.
• State and input implications: Sets run/details Frozen directly. Applies advance-recovery deltas.
• Audit and event implications: Adds compatibility Freeze audit. No native Payroll-frozen outbox event is created by this compatibility path.
• Compatibility notes: Monolith-shaped compatibility contract.
• Safe example: Illustrative body uses period plus an item containing employee/financial placeholders; success → 200 frozen rows
• Example error: "Request could not be completed." (illustrative raw compatibility wording)

Unfreeze salary rows

• API family / maturity: Compatibility Payroll and Salary API; Compatibility
• Authentication / authorization: Bearer expected by the compatibility contract; downstream enforcement Requires confirmation. No endpoint-specific role policy is confirmed.
• Tenant context: Forwarded tenant context expected; no tenant query parameter.
• Route parameters: None.
• Query parameters: None.
• Request body / type: month, year; MonthYearCompatRequest.
• Validation: Only checks stated in the error mapping below are confirmed; model-binding failures are framework behavior and not specified as a stable contract.
• Response body / type: Anonymous message/period/row-count object.
• Success / error responses: 200; 400 raw text when no Frozen rows exist.
• Business behavior: Return Frozen salary rows to editable compatibility state.
• State and input implications: Sets run/details Draft. Does not reverse advance recovery in this compatibility path.
• Audit and event implications: Adds SalaryUnfreeze audit. No native Payroll-unfrozen event is created by this path.
• Compatibility notes: Monolith-shaped compatibility contract.
• Safe example: POST /api/salary/unfreeze with period body → 200 message and affected-row count
• Example error: "Request could not be completed." (illustrative raw compatibility wording)

Read statutory settings

• API family / maturity: Compatibility Payroll and Salary API; Compatibility
• Authentication / authorization: Bearer expected by the compatibility contract; downstream enforcement Requires confirmation. No endpoint-specific role policy is confirmed.
• Tenant context: Forwarded tenant context expected; no tenant query parameter.
• Route parameters: None.
• Query parameters: None.
• Request body / type: None; None.
• Validation: Only checks stated in the error mapping below are confirmed; model-binding failures are framework behavior and not specified as a stable contract.
• Response body / type: Anonymous setting array.
• Success / error responses: 200; No endpoint-specific error response is mapped.
• Business behavior: Return read-only compatibility statutory-setting metadata.
• State and input implications: Read-only. No input projection changes.
• Audit and event implications: No audit side effect confirmed. No event produced.
• Compatibility notes: Read-only transitional ownership; writes remain outside Payroll Service.
• Safe example: GET /api/hr-operations/statutory-settings → 200 []
• Example error: No stable endpoint-specific error example is confirmed.

Family-level findings

Compatibility operations return bare objects, arrays, files, or raw strings. Native and salary-compatibility lifecycle side effects are not identical. Exact financial response fields are source-backed but omitted from examples. There is no compatibility delete-run, approval, finalization, payment, or accounting endpoint.

Source References

• microservices/src/payroll-service/Api/PayrollCompatEndpoints.cs
• microservices/src/payroll-service/Application/PayrollCompatService.cs
• Controllers/PayrollController.cs
• Controllers/SalaryController.cs
• microservices/src/gateway-api/Program.cs

Related Articles

• Payroll API
• Payroll technical documentation

See Also

• Payroll business documentation
• Payroll module

Keywords

• Payroll API
• Compatibility Payroll and Salary API

Revision Information

• Status: Draft
• Last reviewed: 2026-07-15
• Review cycle: Quarterly