Workday Payroll Processing

naftiko: "1.0.0-alpha1"

info:
  label: "Workday Payroll Processing"
  description: >-
    Unified capability for end-to-end payroll processing workflows combining
    the Workday Payroll, Payroll Input, Payroll Results, and Tax APIs. Supports
    HR administrators and payroll specialists running payroll cycles, managing
    worker pay data, submitting adjustments, and reviewing payroll results and
    compliance data.
  tags:
    - Workday
    - Payroll
    - Compensation
    - Human Resources
    - Tax
    - Compliance
  created: "2026-05-03"
  modified: "2026-05-03"

binds:
  - namespace: env
    keys:
      WORKDAY_PAYROLL_TOKEN: WORKDAY_PAYROLL_TOKEN

capability:
  consumes:
    - import: payroll
      location: ./shared/payroll.yaml
    - import: payroll-results
      location: ./shared/payroll-results.yaml
    - import: payroll-input
      location: ./shared/payroll-input.yaml
    - import: payroll-tax
      location: ./shared/payroll-tax.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: payroll-processing-api
      description: "Unified REST API for Workday payroll processing workflows."
      resources:
        - path: /v1/pay-runs
          name: pay-runs
          description: "Payroll run lifecycle management"
          operations:
            - method: GET
              name: list-pay-runs
              description: "List all payroll runs with optional filters"
              call: "payroll.list-pay-runs"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: create-pay-run
              description: "Initiate a new payroll run"
              call: "payroll.create-pay-run"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/pay-runs/{payRunId}
          name: pay-run-by-id
          description: "Manage a specific pay run"
          operations:
            - method: GET
              name: get-pay-run
              description: "Get pay run details"
              call: "payroll.get-pay-run"
              with:
                payRunId: "rest.payRunId"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: PATCH
              name: update-pay-run
              description: "Update a pay run"
              call: "payroll.update-pay-run"
              with:
                payRunId: "rest.payRunId"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/pay-runs/{payRunId}/calculate
          name: pay-run-calculate
          description: "Trigger payroll calculation"
          operations:
            - method: POST
              name: calculate-pay-run
              description: "Trigger payroll calculations for a pay run"
              call: "payroll.calculate-pay-run"
              with:
                payRunId: "rest.payRunId"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/pay-runs/{payRunId}/complete
          name: pay-run-complete
          description: "Complete a pay run"
          operations:
            - method: POST
              name: complete-pay-run
              description: "Mark a pay run as completed"
              call: "payroll.complete-pay-run"
              with:
                payRunId: "rest.payRunId"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/pay-runs/{payRunId}/results
          name: pay-run-results
          description: "Pay run result summaries"
          operations:
            - method: GET
              name: get-pay-run-results
              description: "Get aggregated results for a completed pay run"
              call: "payroll-results.get-pay-run-results"
              with:
                payRunId: "rest.payRunId"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/pay-runs/{payRunId}/worker-results
          name: pay-run-worker-results
          description: "Worker-level results for a pay run"
          operations:
            - method: GET
              name: list-pay-run-worker-results
              description: "List individual worker results for a pay run"
              call: "payroll-results.list-pay-run-worker-results"
              with:
                payRunId: "rest.payRunId"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/pay-runs/{payRunId}/worker-results/{workerId}
          name: pay-run-worker-result-by-id
          description: "Detailed worker result"
          operations:
            - method: GET
              name: get-pay-run-worker-result
              description: "Get detailed result for a worker in a pay run"
              call: "payroll-results.get-pay-run-worker-result"
              with:
                payRunId: "rest.payRunId"
                workerId: "rest.workerId"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/pay-runs/{payRunId}/payments
          name: pay-run-payments
          description: "Payments generated by a pay run"
          operations:
            - method: GET
              name: list-pay-run-payments
              description: "List payments for a completed pay run"
              call: "payroll-results.list-pay-run-payments"
              with:
                payRunId: "rest.payRunId"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/pay-runs/{payRunId}/tax-results
          name: pay-run-tax-results
          description: "Tax results for a pay run"
          operations:
            - method: GET
              name: list-pay-run-tax-results
              description: "List tax calculation results for a pay run"
              call: "payroll-tax.list-pay-run-tax-results"
              with:
                payRunId: "rest.payRunId"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/pay-groups
          name: pay-groups
          description: "Pay group management"
          operations:
            - method: GET
              name: list-pay-groups
              description: "List all pay groups"
              call: "payroll.list-pay-groups"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/pay-groups/{payGroupId}
          name: pay-group-by-id
          description: "Individual pay group"
          operations:
            - method: GET
              name: get-pay-group
              description: "Get a specific pay group"
              call: "payroll.get-pay-group"
              with:
                payGroupId: "rest.payGroupId"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/pay-groups/{payGroupId}/workers
          name: pay-group-workers
          description: "Workers in a pay group"
          operations:
            - method: GET
              name: list-pay-group-workers
              description: "List workers in a pay group"
              call: "payroll.list-pay-group-workers"
              with:
                payGroupId: "rest.payGroupId"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/payments/{paymentId}
          name: payment-by-id
          description: "Individual payment"
          operations:
            - method: GET
              name: get-payment
              description: "Get a specific payment transaction"
              call: "payroll-results.get-payment"
              with:
                paymentId: "rest.paymentId"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/workers/{workerId}/payroll-details
          name: worker-payroll-details
          description: "Worker payroll details"
          operations:
            - method: GET
              name: get-worker-payroll-details
              description: "Get payroll details for a worker"
              call: "payroll.get-worker-payroll-details"
              with:
                workerId: "rest.workerId"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/workers/{workerId}/payslips
          name: worker-payslips
          description: "Worker pay statements"
          operations:
            - method: GET
              name: list-worker-payslips
              description: "List payslips for a worker"
              call: "payroll-results.list-worker-payslips"
              with:
                workerId: "rest.workerId"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/workers/{workerId}/payslips/{payslipId}
          name: worker-payslip-by-id
          description: "Individual payslip"
          operations:
            - method: GET
              name: get-worker-payslip
              description: "Get a specific payslip"
              call: "payroll-results.get-worker-payslip"
              with:
                workerId: "rest.workerId"
                payslipId: "rest.payslipId"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/workers/{workerId}/payment-elections
          name: worker-payment-elections
          description: "Worker payment elections"
          operations:
            - method: GET
              name: list-worker-payment-elections
              description: "List payment elections for a worker"
              call: "payroll-results.list-worker-payment-elections"
              with:
                workerId: "rest.workerId"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/workers/{workerId}/earnings
          name: worker-earnings
          description: "Worker earnings records"
          operations:
            - method: GET
              name: list-worker-earnings
              description: "List earnings for a worker"
              call: "payroll.list-worker-earnings"
              with:
                workerId: "rest.workerId"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/workers/{workerId}/deductions
          name: worker-deductions
          description: "Worker deduction records"
          operations:
            - method: GET
              name: list-worker-deductions
              description: "List deductions for a worker"
              call: "payroll.list-worker-deductions"
              with:
                workerId: "rest.workerId"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/workers/{workerId}/tax-withholdings
          name: worker-tax-withholdings
          description: "Worker tax withholdings"
          operations:
            - method: GET
              name: list-worker-tax-withholdings
              description: "List tax withholdings for a worker"
              call: "payroll-tax.list-worker-tax-withholdings"
              with:
                workerId: "rest.workerId"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/workers/{workerId}/tax-withholdings/{withholdingId}
          name: worker-tax-withholding-by-id
          description: "Individual tax withholding"
          operations:
            - method: GET
              name: get-worker-tax-withholding
              description: "Get a specific tax withholding"
              call: "payroll-tax.get-worker-tax-withholding"
              with:
                workerId: "rest.workerId"
                withholdingId: "rest.withholdingId"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: PATCH
              name: update-worker-tax-withholding
              description: "Update a tax withholding"
              call: "payroll-tax.update-worker-tax-withholding"
              with:
                workerId: "rest.workerId"
                withholdingId: "rest.withholdingId"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/workers/{workerId}/tax-elections
          name: worker-tax-elections
          description: "Worker tax elections"
          operations:
            - method: GET
              name: list-worker-tax-elections
              description: "List tax elections for a worker"
              call: "payroll-tax.list-worker-tax-elections"
              with:
                workerId: "rest.workerId"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: create-worker-tax-election
              description: "Submit a new W-4 or state tax election"
              call: "payroll-tax.create-worker-tax-election"
              with:
                workerId: "rest.workerId"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/workers/{workerId}/tax-elections/{electionId}
          name: worker-tax-election-by-id
          description: "Individual tax election"
          operations:
            - method: GET
              name: get-worker-tax-election
              description: "Get a specific tax election"
              call: "payroll-tax.get-worker-tax-election"
              with:
                workerId: "rest.workerId"
                electionId: "rest.electionId"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/workers/{workerId}/tax-summary
          name: worker-tax-summary
          description: "Worker tax summary"
          operations:
            - method: GET
              name: get-worker-tax-summary
              description: "Get year-to-date tax summary"
              call: "payroll-tax.get-worker-tax-summary"
              with:
                workerId: "rest.workerId"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/workers/{workerId}/time-off-inputs
          name: worker-time-off-inputs
          description: "Worker time off inputs"
          operations:
            - method: GET
              name: list-worker-time-off-inputs
              description: "List time off inputs for a worker"
              call: "payroll-input.list-worker-time-off-inputs"
              with:
                workerId: "rest.workerId"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: create-worker-time-off-input
              description: "Submit a time off input"
              call: "payroll-input.create-worker-time-off-input"
              with:
                workerId: "rest.workerId"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/one-time-payments
          name: one-time-payments
          description: "One-time payment requests"
          operations:
            - method: GET
              name: list-one-time-payments
              description: "List one-time payment requests"
              call: "payroll-input.list-one-time-payments"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: create-one-time-payment
              description: "Submit a one-time payment"
              call: "payroll-input.create-one-time-payment"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/one-time-payments/{paymentId}
          name: one-time-payment-by-id
          description: "Individual one-time payment"
          operations:
            - method: GET
              name: get-one-time-payment
              description: "Get a specific one-time payment"
              call: "payroll-input.get-one-time-payment"
              with:
                paymentId: "rest.paymentId"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: PATCH
              name: update-one-time-payment
              description: "Update a pending one-time payment"
              call: "payroll-input.update-one-time-payment"
              with:
                paymentId: "rest.paymentId"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: DELETE
              name: delete-one-time-payment
              description: "Delete a pending one-time payment"
              call: "payroll-input.delete-one-time-payment"
              with:
                paymentId: "rest.paymentId"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/adjustments
          name: adjustments
          description: "Payroll adjustments and corrections"
          operations:
            - method: GET
              name: list-payroll-adjustments
              description: "List payroll adjustments"
              call: "payroll-input.list-payroll-adjustments"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: create-payroll-adjustment
              description: "Submit a payroll adjustment"
              call: "payroll-input.create-payroll-adjustment"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/adjustments/{adjustmentId}
          name: adjustment-by-id
          description: "Individual payroll adjustment"
          operations:
            - method: GET
              name: get-payroll-adjustment
              description: "Get a specific payroll adjustment"
              call: "payroll-input.get-payroll-adjustment"
              with:
                adjustmentId: "rest.adjustmentId"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/supplemental-earnings
          name: supplemental-earnings
          description: "Supplemental earnings (bonuses, commissions)"
          operations:
            - method: GET
              name: list-supplemental-earnings
              description: "List supplemental earnings"
              call: "payroll-input.list-supplemental-earnings"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: create-supplemental-earning
              description: "Submit a supplemental earning"
              call: "payroll-input.create-supplemental-earning"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/supplemental-earnings/{earningId}
          name: supplemental-earning-by-id
          description: "Individual supplemental earning"
          operations:
            - method: GET
              name: get-supplemental-earning
              description: "Get a specific supplemental earning"
              call: "payroll-input.get-supplemental-earning"
              with:
                earningId: "rest.earningId"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: DELETE
              name: delete-supplemental-earning
              description: "Delete a pending supplemental earning"
              call: "payroll-input.delete-supplemental-earning"
              with:
                earningId: "rest.earningId"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/input-batches
          name: input-batches
          description: "Batch payroll input submissions"
          operations:
            - method: GET
              name: list-input-batches
              description: "List input batches"
              call: "payroll-input.list-input-batches"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: create-input-batch
              description: "Submit a batch of payroll inputs"
              call: "payroll-input.create-input-batch"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/input-batches/{batchId}
          name: input-batch-by-id
          description: "Individual input batch"
          operations:
            - method: GET
              name: get-input-batch
              description: "Get a specific input batch"
              call: "payroll-input.get-input-batch"
              with:
                batchId: "rest.batchId"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/earning-codes
          name: earning-codes
          description: "Earning code reference data"
          operations:
            - method: GET
              name: list-earning-codes
              description: "List configured earning codes"
              call: "payroll.list-earning-codes"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/deduction-codes
          name: deduction-codes
          description: "Deduction code reference data"
          operations:
            - method: GET
              name: list-deduction-codes
              description: "List configured deduction codes"
              call: "payroll.list-deduction-codes"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/tax-jurisdictions
          name: tax-jurisdictions
          description: "Tax jurisdiction reference data"
          operations:
            - method: GET
              name: list-tax-jurisdictions
              description: "List supported tax jurisdictions"
              call: "payroll-tax.list-tax-jurisdictions"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/tax-jurisdictions/{jurisdictionId}
          name: tax-jurisdiction-by-id
          description: "Individual tax jurisdiction"
          operations:
            - method: GET
              name: get-tax-jurisdiction
              description: "Get a specific tax jurisdiction"
              call: "payroll-tax.get-tax-jurisdiction"
              with:
                jurisdictionId: "rest.jurisdictionId"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/tax-filings
          name: tax-filings
          description: "Tax filings"
          operations:
            - method: GET
              name: list-tax-filings
              description: "List tax filings"
              call: "payroll-tax.list-tax-filings"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/tax-filings/{filingId}
          name: tax-filing-by-id
          description: "Individual tax filing"
          operations:
            - method: GET
              name: get-tax-filing
              description: "Get a specific tax filing"
              call: "payroll-tax.get-tax-filing"
              with:
                filingId: "rest.filingId"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9090
      namespace: payroll-processing-mcp
      transport: http
      description: "MCP server for AI-assisted payroll processing and compensation management."
      tools:
        - name: list-pay-runs
          description: "List payroll runs with optional filters by status, pay group, or date"
          hints:
            readOnly: true
            idempotent: true
          call: "payroll.list-pay-runs"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-pay-run
          description: "Get details of a specific payroll run"
          hints:
            readOnly: true
            idempotent: true
          call: "payroll.get-pay-run"
          with:
            payRunId: "tools.payRunId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: create-pay-run
          description: "Initiate a new payroll run for a pay group"
          hints:
            readOnly: false
            idempotent: false
          call: "payroll.create-pay-run"
          outputParameters:
            - type: object
              mapping: "$."
        - name: update-pay-run
          description: "Update the status or properties of a pay run"
          hints:
            readOnly: false
            idempotent: true
          call: "payroll.update-pay-run"
          with:
            payRunId: "tools.payRunId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: calculate-pay-run
          description: "Trigger payroll calculations for a pay run"
          hints:
            readOnly: false
            destructive: true
            idempotent: false
          call: "payroll.calculate-pay-run"
          with:
            payRunId: "tools.payRunId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: complete-pay-run
          description: "Mark a pay run as completed and finalize payments"
          hints:
            readOnly: false
            destructive: true
            idempotent: false
          call: "payroll.complete-pay-run"
          with:
            payRunId: "tools.payRunId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-pay-run-results
          description: "Get aggregated totals for a completed pay run"
          hints:
            readOnly: true
            idempotent: true
          call: "payroll-results.get-pay-run-results"
          with:
            payRunId: "tools.payRunId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-pay-run-worker-results
          description: "List individual worker results for a pay run"
          hints:
            readOnly: true
            idempotent: true
          call: "payroll-results.list-pay-run-worker-results"
          with:
            payRunId: "tools.payRunId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-pay-run-worker-result
          description: "Get detailed result for a specific worker in a pay run"
          hints:
            readOnly: true
            idempotent: true
          call: "payroll-results.get-pay-run-worker-result"
          with:
            payRunId: "tools.payRunId"
            workerId: "tools.workerId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-pay-run-payments
          description: "List payment transactions generated by a pay run"
          hints:
            readOnly: true
            idempotent: true
          call: "payroll-results.list-pay-run-payments"
          with:
            payRunId: "tools.payRunId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-payment
          description: "Get details of a specific payment transaction"
          hints:
            readOnly: true
            idempotent: true
          call: "payroll-results.get-payment"
          with:
            paymentId: "tools.paymentId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-pay-run-tax-results
          description: "List tax calculation results for a completed pay run"
          hints:
            readOnly: true
            idempotent: true
          call: "payroll-tax.list-pay-run-tax-results"
          with:
            payRunId: "tools.payRunId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-pay-groups
          description: "List all configured pay groups"
          hints:
            readOnly: true
            idempotent: true
          call: "payroll.list-pay-groups"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-pay-group
          description: "Get details of a specific pay group"
          hints:
            readOnly: true
            idempotent: true
          call: "payroll.get-pay-group"
          with:
            payGroupId: "tools.payGroupId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-pay-group-workers
          description: "List workers in a pay group"
          hints:
            readOnly: true
            idempotent: true
          call: "payroll.list-pay-group-workers"
          with:
            payGroupId: "tools.payGroupId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-worker-payroll-details
          description: "Get payroll configuration details for a worker"
          hints:
            readOnly: true
            idempotent: true
          call: "payroll.get-worker-payroll-details"
          with:
            workerId: "tools.workerId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-worker-payslips
          description: "List pay statements for a worker"
          hints:
            readOnly: true
            idempotent: true
          call: "payroll-results.list-worker-payslips"
          with:
            workerId: "tools.workerId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-worker-payslip
          description: "Get detailed payslip with earnings, deductions, and taxes"
          hints:
            readOnly: true
            idempotent: true
          call: "payroll-results.get-worker-payslip"
          with:
            workerId: "tools.workerId"
            payslipId: "tools.payslipId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-worker-payment-elections
          description: "List direct deposit and payment preferences for a worker"
          hints:
            readOnly: true
            idempotent: true
          call: "payroll-results.list-worker-payment-elections"
          with:
            workerId: "tools.workerId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-worker-earnings
          description: "List earnings records for a worker"
          hints:
            readOnly: true
            idempotent: true
          call: "payroll.list-worker-earnings"
          with:
            workerId: "tools.workerId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-worker-deductions
          description: "List deductions for a worker"
          hints:
            readOnly: true
            idempotent: true
          call: "payroll.list-worker-deductions"
          with:
            workerId: "tools.workerId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-worker-tax-withholdings
          description: "List tax withholding configurations for a worker"
          hints:
            readOnly: true
            idempotent: true
          call: "payroll-tax.list-worker-tax-withholdings"
          with:
            workerId: "tools.workerId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-worker-tax-withholding
          description: "Get a specific tax withholding for a worker"
          hints:
            readOnly: true
            idempotent: true
          call: "payroll-tax.get-worker-tax-withholding"
          with:
            workerId: "tools.workerId"
            withholdingId: "tools.withholdingId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: update-worker-tax-withholding
          description: "Update a tax withh

# --- truncated at 32 KB (41 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/workday-payroll/refs/heads/main/capabilities/payroll-processing.yaml