Blocks

ConfirmWireDetails

Wire transfer confirmation workflow for payroll funding.

Displays a banner when wire transfers are awaiting funds and walks the user through viewing wire instructions and confirming transfer details via a modal.

Example

import { Payroll } from '@gusto/embedded-react-sdk'

function MyComponent() {
  return (
    <Payroll.ConfirmWireDetails
      companyId="your-company-id"
      wireInId="your-wire-in-id"
      onEvent={() => {}}
    />
  )
}

ConfirmWireDetailsProps

Props for the ConfirmWireDetails component.

Property	Type	Description
companyId	string	The associated company identifier.
onEvent	OnEventType<EventType, unknown>	Callback invoked each time the component emits an event — user interactions, successful API responses, step transitions, or errors. Receives the event type constant and an optional payload whose shape varies by event. See the Event Handling guide and each component's event table for the full list of emitted events.
dictionary?	Record<"en", DeepPartial<PayrollConfirmWireDetailsForm>>	Overrides for the component's i18n strings. Supply a partial object whose keys match the component's resource namespace — any omitted keys fall back to SDK defaults. See the Translation guide for details.
wireInId?	string	Optional wire-in request identifier. If not provided, the first active wire-in request is used.

Inherits children, className, defaultValues, FallbackComponent, LoaderComponent from BaseComponentInterface.

Events

Event	Description	Data
payroll/wire/startTransfer	User initiates the wire transfer flow	—
payroll/wire/instructions/select	User selects a wire-in request from the instructions screen	{ selectedWireInId: string }
payroll/wire/instructions/done	User completes viewing wire instructions	{ selectedWireInId: string }
payroll/wire/instructions/cancel	User cancels viewing wire instructions	—
payroll/wire/form/done	User completes the wire confirmation form	{ wireInRequest: WireInRequest }
payroll/wire/form/cancel	User cancels the wire confirmation form	—

Endpoints

Method	Path
GET	/v1/companies/:companyId/payrolls
GET	/v1/companies/:companyUuid/wire_in_requests
GET	/v1/wire_in_requests/:wireInRequestUuid
PUT	/v1/wire_in_requests/:wireInRequestUuid

---

DismissalPayPeriodSelection

Pay period selection step for the dismissal payroll workflow.

Lists the terminated employee's unprocessed termination pay periods and, on submit, creates an off-cycle payroll with the "Dismissed employee" reason for the selected period. When only one pay period is available it is pre-selected. When both payrollId and employeeId are supplied the step is skipped and the selection event fires immediately with the existing payroll.

Remarks

Events:

DismissalPayPeriodSelectionProps

Props for DismissalPayPeriodSelection.

Property	Type	Description
companyId	string	Identifier of the company the dismissal payroll belongs to.
onEvent	OnEventType<EventType, unknown>	Callback invoked each time the component emits an event — user interactions, successful API responses, step transitions, or errors. Receives the event type constant and an optional payload whose shape varies by event. See the Event Handling guide and each component's event table for the full list of emitted events.
dictionary?	Record<"en", DeepPartial<PayrollDismissal>>	Overrides for the component's i18n strings. Supply a partial object whose keys match the component's resource namespace — any omitted keys fall back to SDK defaults. See the Translation guide for details.
employeeId?	string	Identifier of the terminated employee. When provided, the available pay periods are filtered to this employee.
payrollId?	string	Identifier of an existing dismissal payroll. When provided alongside employeeId, pay period selection is skipped and the component immediately emits the selection event.

Inherits children, className, defaultValues, FallbackComponent, LoaderComponent from BaseComponentInterface.

Events

Event	Description	Data
dismissal/payPeriod/selected	Fired after a pay period is selected and the off-cycle payroll has been created, or immediately when payrollId is supplied.	{ payrollUuid: string }

Endpoints

Method	Path
GET	/v1/companies/:companyId/pay_periods/unprocessed_termination_pay_periods
POST	/v1/companies/:companyId/payrolls
GET	/v1/companies/:companyId/payrolls/:payrollId

---

OffCycleCreation

Creation form for off-cycle (bonus or correction) payrolls.

Walks the user through configuring pay period dates, selecting a reason, choosing employees, and setting deduction and tax withholding preferences, then submits the resulting payroll for execution.

OffCycleCreationProps

Props for the OffCycleCreation component.

Property	Type	Description
companyId	string	The associated company identifier.
onEvent	OnEventType<EventType, unknown>	Callback invoked each time the component emits an event — user interactions, successful API responses, step transitions, or errors. Receives the event type constant and an optional payload whose shape varies by event. See the Event Handling guide and each component's event table for the full list of emitted events.
dictionary?	Record<"en", DeepPartial<PayrollOffCycleCreation>>	Overrides for the component's i18n strings. Supply a partial object whose keys match the component's resource namespace — any omitted keys fall back to SDK defaults. See the Translation guide for details.
payrollType?	OffCyclePayrollDateType	Pre-selected off-cycle reason. The creation form starts with this reason selected. Defaults to 'bonus'.

Inherits children, className, defaultValues, FallbackComponent, LoaderComponent from BaseComponentInterface.

Events

Event	Description	Data
offCycle/created	The off-cycle payroll has been created	{ payrollUuid: string }
offCycle/blockers/viewAll	The user chose to view the company's payroll blockers from the blocker alert	none

Changing the reason updates the deduction and withholding defaults — 'bonus' skips regular deductions and uses the supplemental withholding rate; 'correction' includes regular deductions and uses the regular rate.

Endpoints

Method	Path
GET	/v1/companies/:companyId/employees
POST	/v1/companies/:companyId/payrolls
GET	/v1/companies/:companyUuid/payment_configs
GET	/v1/companies/:companyUuid/payrolls/blockers

---

OffCycleDeductionsSetting

Radio control for choosing whether an off-cycle payroll skips regular deductions and contributions.

Remarks

Taxes are always included regardless of the selection. Selecting "Skip" blocks all regular deductions and contributions except 401(k); selecting "Include" runs all regular deductions and contributions normally.

OffCycleDeductionsSettingProps

Props for OffCycleDeductionsSetting.

Property	Type	Description
onEvent	OnEventType<EventType, unknown>	Event handler invoked when the deduction preference changes. See the events table on OffCycleDeductionsSetting.
skipRegularDeductions	boolean	Whether regular deductions are currently being skipped.
dictionary?	Record<"en", DeepPartial<PayrollOffCycleDeductionsSetting>>	Overrides for the component's i18n strings. Supply a partial object whose keys match the component's resource namespace — any omitted keys fall back to SDK defaults. See the Translation guide for details.

Inherits children, className, defaultValues from CommonComponentInterface.

Events

Event	Description	Data
offCycle/deductionsChange	Fired when the deduction preference changes	OffCycleDeductionsSettingChangePayload

---

OffCycleReasonSelection

Presents the reason selection UI for choosing between a bonus and correction off-cycle payment.

Remarks

Selecting a reason emits the recommended deduction and withholding defaults alongside the chosen value so a surrounding form can update its state to match.

OffCycleReasonSelectionProps

Props for the OffCycleReasonSelection component.

Property	Type	Description
companyId	string	The associated company identifier.
onEvent	OnEventType<EventType, unknown>	Callback invoked each time the component emits an event — user interactions, successful API responses, step transitions, or errors. Receives the event type constant and an optional payload whose shape varies by event. See the Event Handling guide and each component's event table for the full list of emitted events.
dictionary?	Record<"en", DeepPartial<PayrollOffCycleReasonSelection>>	Overrides for the component's i18n strings. Supply a partial object whose keys match the component's resource namespace — any omitted keys fall back to SDK defaults. See the Translation guide for details.

Inherits children, className, defaultValues, FallbackComponent, LoaderComponent from BaseComponentInterface.

Events

Event	Description	Data
offCycle/selectReason	Fired when the user selects a reason	SelectReasonPayload

---

PayrollBlockerList

Displays the list of blockers preventing payroll from being processed for a company.

Remarks

Blockers indicate issues that must be resolved before a payroll can be calculated or submitted, such as missing employee information, invalid tax setups, or incomplete company configuration. The component also renders open recovery cases and outstanding information requests for the company when present, and re-emits any events those embedded surfaces fire through onEvent.

PayrollBlockerListProps

Props for PayrollBlockerList.

Property	Type	Description
companyId	string	The associated company identifier.
onEvent	OnEventType<EventType, unknown>	Callback invoked each time the component emits an event — user interactions, successful API responses, step transitions, or errors. Receives the event type constant and an optional payload whose shape varies by event. See the Event Handling guide and each component's event table for the full list of emitted events.
dictionary?	Record<"en", DeepPartial<PayrollPayrollBlocker>>	Overrides for the component's i18n strings. Supply a partial object whose keys match the component's resource namespace — any omitted keys fall back to SDK defaults. See the Translation guide for details.

Inherits children, className, defaultValues, FallbackComponent, LoaderComponent from BaseComponentInterface.

Endpoints

Method	Path
GET	/v1/companies/:companyUuid/payrolls/blockers

---

PayrollConfiguration

Handles the configuration phase of payroll processing, allowing users to review and modify employee compensation before calculating the payroll.

Remarks

If the payroll turns out to already be processed (e.g. another actor submitted it while this screen was open), this component emits runPayroll/alreadyProcessed and then renders PayrollOverview in its place — the read-only breakdown with the gated "Cancel payroll" action — instead of the configuration table. Events from that delegated view (e.g. runPayroll/cancelled) are emitted through this component's own onEvent.

Emits the following events:

PayrollConfigurationProps

Props for PayrollConfiguration.

Property	Type	Description
companyId	string	The associated company identifier.
onEvent	OnEventType<EventType, unknown>	Callback invoked each time the component emits an event — user interactions, successful API responses, step transitions, or errors. Receives the event type constant and an optional payload whose shape varies by event. See the Event Handling guide and each component's event table for the full list of emitted events.
payrollId	string	The associated payroll identifier.
alerts?	ReactNode	Optional alert components to render above the configuration content.
dictionary?	Record<"en", DeepPartial<PayrollPayrollConfiguration>>	Overrides for the component's i18n strings. Supply a partial object whose keys match the component's resource namespace — any omitted keys fall back to SDK defaults. See the Translation guide for details.
withReimbursements?	boolean	Whether to show the reimbursements column in the compensation table. Defaults to true.

Inherits children, className, defaultValues, FallbackComponent, LoaderComponent from BaseComponentInterface.

Events

Event	Description	Data
runPayroll/employee/edit	An employee row is selected for editing	{ payrollId, employeeId, firstName, lastName }
runPayroll/employee/skip	An employee is skipped or unskipped for this payroll	{ employeeId }
runPayroll/employee/saved	Employee compensation changes are persisted	{ payrollPrepared }
runPayroll/calculated	Payroll calculation completes successfully	{ payrollId, alert, payPeriod }
runPayroll/alreadyProcessed	The payroll turns out to already be processed while configuring it	{ payrollId, alert, payPeriod }
runPayroll/processingFailed	Payroll calculation fails or times out	—
runPayroll/blockers/viewAll	The "view all blockers" affordance is selected	—
runPayroll/grossUp/selected	The set-net-earnings menu item is selected for an employee	{ employeeUuid }
runPayroll/grossUp/calculated	A gross-up amount is calculated from a target net pay	{ grossUp, netPay, employeeUuid }

Endpoints

Method	Path
GET	/v1/companies/:companyId/employees
GET	/v1/companies/:companyId/pay_schedules/:payScheduleId
GET	/v1/companies/:companyId/payrolls/:payrollId
PUT	/v1/companies/:companyId/payrolls/:payrollId
PUT	/v1/companies/:companyId/payrolls/:payrollId/calculate
PUT	/v1/companies/:companyId/payrolls/:payrollId/prepare
GET	/v1/companies/:companyUuid/payrolls/blockers
GET	/v1/employees/:employeeId
POST	/v1/payrolls/:payrollUuid/gross_up

---

PayrollEditEmployee

Editor for an individual employee's compensation within a payroll run.

Allows modification of pay rates, hours, time off, additional earnings, reimbursements, and payment method for a single employee on the specified payroll.

Example

import { Payroll } from '@gusto/embedded-react-sdk'

function MyComponent() {
  return (
    <Payroll.PayrollEditEmployee
      employeeId="your-employee-id"
      companyId="your-company-id"
      payrollId="your-payroll-id"
      onEvent={() => {}}
    />
  )
}

PayrollEditEmployeeProps

Props for PayrollEditEmployee.

Property	Type	Description
companyId	string	The associated company identifier.
employeeId	string	The associated employee identifier.
onEvent	OnEventType<EventType, unknown>	Callback invoked each time the component emits an event — user interactions, successful API responses, step transitions, or errors. Receives the event type constant and an optional payload whose shape varies by event. See the Event Handling guide and each component's event table for the full list of emitted events.
payrollId	string	The associated payroll identifier.
dictionary?	Record<"en", DeepPartial<PayrollPayrollEditEmployee>>	Overrides for the component's i18n strings. Supply a partial object whose keys match the component's resource namespace — any omitted keys fall back to SDK defaults. See the Translation guide for details.
withReimbursements?	boolean	Whether to show reimbursement fields. Defaults to true.

Inherits children, className, defaultValues, FallbackComponent, LoaderComponent from BaseComponentInterface.

Events

Event	Description	Data
runPayroll/employee/saved	Fired when employee payroll compensation changes are saved	{ payrollPrepared, employee }
runPayroll/employee/cancelled	Fired when the user cancels editing employee payroll compensation	—

Endpoints

Method	Path
GET	/v1/companies/:companyId/earning_types
GET	/v1/companies/:companyId/pay_schedules/:payScheduleId
GET	/v1/companies/:companyId/payrolls/:payrollId
PUT	/v1/companies/:companyId/payrolls/:payrollId
PUT	/v1/companies/:companyId/payrolls/:payrollId/prepare
GET	/v1/employees/:employeeId
GET	/v1/employees/:employeeId/bank_accounts

---

PayrollHistory

Displays historical payroll records with filtering and management capabilities.

Remarks

Lists processed regular, off-cycle, and external payrolls for a company and supports filtering by pay period, viewing payroll summaries and receipts, and cancelling processed payrolls when they remain within the cancellation window. Each row shows the pay period, payroll type, pay date, status, and total pay amount.

PayrollHistoryProps

Props for the PayrollHistory component.

Property	Type	Description
companyId	string	Identifier of the company whose processed payrolls should be listed.
onEvent	OnEventType<EventType, unknown>	Callback invoked each time the component emits an event — user interactions, successful API responses, step transitions, or errors. Receives the event type constant and an optional payload whose shape varies by event. See the Event Handling guide and each component's event table for the full list of emitted events.
dictionary?	Record<"en", DeepPartial<PayrollPayrollHistory>>	Overrides for the component's i18n strings. Supply a partial object whose keys match the component's resource namespace — any omitted keys fall back to SDK defaults. See the Translation guide for details.

Inherits children, className, defaultValues, FallbackComponent, LoaderComponent from BaseComponentInterface.

Events

Event	Description	Data
runPayroll/summary/viewed	User views a payroll summary	{ payrollId: string; startDate?: string; endDate?: string }
runPayroll/receipt/viewed	User views a payroll receipt	{ payrollId: string; startDate?: string; endDate?: string }
runPayroll/cancelled	A payroll is cancelled	{ payrollId: string; result: PayrollsCancelResponse }

Endpoints

Method	Path
GET	/v1/companies/:companyId/payrolls
PUT	/v1/companies/:companyId/payrolls/:payrollId/cancel
GET	/v1/companies/:companyUuid/wire_in_requests

---

PayrollLanding

Main landing surface for payroll operations, with tabs for running payroll and viewing payroll history, plus inline navigation to a payroll's overview and receipt.

PayrollLandingProps

Props for PayrollLanding.

Property	Type	Description
companyId	string	The associated company identifier.
onEvent	OnEventType<EventType, unknown>	Callback invoked each time the component emits an event — user interactions, successful API responses, step transitions, or errors. Receives the event type constant and an optional payload whose shape varies by event. See the Event Handling guide and each component's event table for the full list of emitted events.
ConfirmWireDetailsComponent?	ConfirmWireDetailsComponentType	Custom component that replaces the default wire details confirmation UI.
dictionary?	Record<"en", DeepPartial<PayrollPayrollLanding>>	Overrides for the component's i18n strings. Supply a partial object whose keys match the component's resource namespace — any omitted keys fall back to SDK defaults. See the Translation guide for details.
showPayrollCancelledAlert?	boolean	When true, displays a dismissible success alert indicating a payroll was cancelled.
withOffcyclePayroll?	boolean	Whether to show the off-cycle payroll call-to-action. Defaults to true.
withReimbursements?	boolean	Whether to show reimbursement fields throughout the landing flow. Defaults to true.

Inherits children, className, defaultValues, FallbackComponent, LoaderComponent from BaseComponentInterface.

Events

Event	Description	Data
runPayroll/selected	User selected a payroll to run	{ payrollUuid: string, payPeriod: object }
payroll/review	User selected a calculated payroll to review	{ payrollUuid: string, payPeriod: object }
payroll/skipped	A payroll was skipped	{ payrollId: string }
payroll/deleted	A cancellable off-cycle payroll was deleted	{ payrollId: string }
runPayroll/offCycle/start	User clicked the Run off-cycle call-to-action	—
transition/runPayroll	User chose to run an unprocessed transition payroll from the Transition Payroll Alert	{ startDate: string, endDate: string, payScheduleUuid?: string }
transition/payrollSkipped	User skipped an unprocessed transition payroll from the Transition Payroll Alert	{ startDate: string, endDate: string, payScheduleUuid?: string }
runPayroll/summary/viewed	User opened a payroll's summary view	{ payrollId: string }
runPayroll/receipt/viewed	User opened a payroll's receipt view	{ payrollId: string }
runPayroll/blockers/viewAll	User opened the full list of payroll blockers	—
runPayroll/cancelled	A payroll was cancelled	{ payrollId: string, result: object }
runPayroll/notCalculated/backToList	User returns to the payroll list from a payroll that is no longer calculated	—
runPayroll/cancelled/alertDismissed	User dismissed the payroll-cancelled success alert	—

When unprocessed transition pay periods exist, the landing surface renders a Transition Payroll Alert. It looks ahead 90 days for upcoming transition periods, groups them by pay schedule, and offers to run or skip each one. Choosing to run emits transition/runPayroll (handle it by rendering Payroll.TransitionFlow with the supplied dates and pay schedule). Skipping opens a confirmation dialog — warning that employees will not be paid for the period — then skips the payroll and emits transition/payrollSkipped. Transition pay periods should be resolved (run or skipped) before regular payrolls are run; the Gusto API may reject regular payrolls while unresolved transition periods exist.

Endpoints

Method	Path
GET	/v1/companies/:companyId/pay_periods
GET	/v1/companies/:companyId/pay_schedules
GET	/v1/companies/:companyUuid/payrolls/blockers
POST	/v1/companies/:companyUuid/payrolls/skip
GET	/v1/companies/:companyUuid/wire_in_requests

---

PayrollList

Lists upcoming payrolls and lets users start running them.

Displays available payrolls with pay period dates, payroll type, check date, deadline, and status. Each row offers actions to run, submit a calculated payroll, skip, or delete (for cancellable off-cycle payrolls). A separate call-to-action starts an off-cycle payroll.

Remarks

When the company has unprocessed transition pay periods within the next 90 days, the Run Payroll action on Regular rows is disabled to prevent a regular payroll from being run before the transition is resolved. Off-cycle rows and the Run off-cycle action remain enabled, since off-cycle is the path used to run a transition payroll. PayrollLanding pairs this list with an alert that lets users run or skip the pending transition; when using PayrollList directly, render an equivalent resolution surface alongside it.

PayrollListBlockProps

Props for PayrollList.

Property	Type	Description
companyId	string	The associated company identifier.
onEvent	OnEventType<EventType, unknown>	Callback invoked each time the component emits an event — user interactions, successful API responses, step transitions, or errors. Receives the event type constant and an optional payload whose shape varies by event. See the Event Handling guide and each component's event table for the full list of emitted events.
withOffcyclePayroll?	boolean	Whether to show the off-cycle payroll call-to-action. Defaults to true.

Inherits children, className, defaultValues, dictionary, FallbackComponent, LoaderComponent from BaseComponentInterface.

Events

Event	Description	Data
runPayroll/selected	User selected a payroll to run	{ payrollUuid, payPeriod }
payroll/review	User selected a calculated payroll to review and submit	{ payrollUuid, payPeriod }
payroll/skipped	A payroll was successfully skipped	{ payrollId }
payroll/deleted	A cancellable off-cycle payroll was successfully deleted	{ payrollId }
runPayroll/offCycle/start	User clicked the Run off-cycle call-to-action	—

Endpoints

Method	Path
GET	/v1/companies/:companyId/pay_periods
GET	/v1/companies/:companyId/pay_schedules
GET	/v1/companies/:companyId/payrolls
DELETE	/v1/companies/:companyId/payrolls/:payrollId
GET	/v1/companies/:companyUuid/payrolls/blockers
POST	/v1/companies/:companyUuid/payrolls/skip
GET	/v1/companies/:companyUuid/wire_in_requests

---

PayrollOverview

Final review screen for a calculated payroll before submission, with submit, cancel, and edit controls. After submission, tracks processing status and surfaces the receipt and per-employee paystub downloads once complete.

Remarks

An unprocessed payroll referenced by payrollId must already be calculated; rendering an unprocessed, uncalculated payroll throws. Processed payrolls render as a summary even without a calculation (for example tax reconciliation, reversal, wage correction, or external payrolls). Unresolved submission blockers (e.g. fast-ACH threshold, wire-in funding) are surfaced inline and the submit action stays disabled until each blocker has a selected unblock option. While the payroll is processing, the component polls until success or failure and emits the corresponding event. Pass readOnly to hide the edit and cancel actions while keeping submit available.

PayrollOverviewProps

Props for PayrollOverview.

Property	Type	Description
companyId	string	Identifier of the company that owns the payroll.
onEvent	OnEventType<EventType, unknown>	Callback invoked each time the component emits an event — user interactions, successful API responses, step transitions, or errors. Receives the event type constant and an optional payload whose shape varies by event. See the Event Handling guide and each component's event table for the full list of emitted events.
payrollId	string	Identifier of the payroll being reviewed. An unprocessed payroll must already be calculated; a processed payroll renders as a summary whether or not it has a calculation.
alerts?	PayrollFlowAlert[]	Alert banners to display above the payroll summary.
ConfirmWireDetailsComponent?	ConfirmWireDetailsComponentType	Custom component to replace the default wire details confirmation UI.
dictionary?	Record<"en", DeepPartial<PayrollPayrollOverview>>	Overrides for the component's i18n strings. Supply a partial object whose keys match the component's resource namespace — any omitted keys fall back to SDK defaults. See the Translation guide for details.
readOnly?	boolean	Hides the edit and cancel actions, leaving submit and receipt/paystub actions available. Use for a deep link to a specific payroll where editing shouldn't be offered. Defaults to false.
withReimbursements?	boolean	Whether reimbursement fields are shown in the totals and per-employee tables. Defaults to true.

Inherits children, className, defaultValues, FallbackComponent, LoaderComponent from BaseComponentInterface.

Events

Event	Description	Data
runPayroll/edit	User chose to edit the payroll before submitting	—
runPayroll/submitting	Submit request was sent to the API	—
runPayroll/submitted	Payroll was successfully submitted	Submit payroll response
runPayroll/processed	Payroll finished processing successfully	{ payPeriod, payrollUuid }
runPayroll/processingFailed	Payroll processing failed	—
runPayroll/cancelled	Payroll was cancelled	Cancel payroll response
runPayroll/notCalculated/backToList	User chose to return to the payroll list after the payroll was found to be no longer calculated (e.g. cancelled in another session)	—
runPayroll/receipt/get	User requested the payroll receipt	{ payrollId }
runPayroll/pdfPaystub/viewed	User opened an employee's paystub PDF	{ employeeId }
payroll/wire/form/done	Wire-in details were confirmed via the embedded wire form	Submit wire-in response
payroll/printChecks/start	User opened the print-checks modal from the embedded print-checks banner	—
payroll/printChecks/generate/start	User submitted the print-checks form	—
payroll/printChecks/generate/succeeded	Printable checks finished generating	{ documentUrl }
payroll/printChecks/generate/failed	The print-checks request was rejected or generation failed	{ errorMessage }
payroll/printChecks/retry	User retried after a failed check generation	—
payroll/printChecks/cancel	User cancelled the print-checks form	—
payroll/printChecks/close	User closed the print-checks failure or summary screen	—

Endpoints

Method	Path
GET	/v1/companies/:companyId/bank_accounts
GET	/v1/companies/:companyId/employees
GET	/v1/companies/:companyId/payrolls/:payrollId
PUT	/v1/companies/:companyId/payrolls/:payrollId/cancel
PUT	/v1/companies/:companyId/payrolls/:payrollId/submit
GET	/v1/companies/:companyUuid/payment_configs
GET	/v1/payrolls/:payrollId/employees/:employeeId/pay_stub
GET	/v1/wire_in_requests/:wireInRequestUuid

---

PayrollReceipts

Displays a detailed receipt for a completed payroll, including the debited total, per-category breakdown, tax breakdown, and a per-employee summary of payment method, garnishments, reimbursements, taxes, and net pay.

Example

import { Payroll } from '@gusto/embedded-react-sdk'

function MyComponent() {
  return <Payroll.PayrollReceipts payrollId="your-payroll-id" onEvent={() => {}} />
}

PayrollReceiptsProps

Props for PayrollReceipts.

Property	Type	Description
onEvent	OnEventType<EventType, unknown>	Callback invoked each time the component emits an event — user interactions, successful API responses, step transitions, or errors. Receives the event type constant and an optional payload whose shape varies by event. See the Event Handling guide and each component's event table for the full list of emitted events.
payrollId	string	Identifier of the payroll whose receipt should be displayed.
dictionary?	Record<"en", DeepPartial<PayrollPayrollReceipts>>	Overrides for the component's i18n strings. Supply a partial object whose keys match the component's resource namespace — any omitted keys fall back to SDK defaults. See the Translation guide for details.
withReimbursements?	boolean	Whether to include reimbursement amounts in the breakdown and employee tables. Defaults to true.

Inherits children, className, defaultValues, FallbackComponent, LoaderComponent from BaseComponentInterface.

Endpoints

Method	Path
GET	/v1/payrolls/:payrollUuid/receipt

---

PrintChecks

Displays a banner prompting the user to print checks for employees paid by check on a processed payroll, and walks them through choosing check stock and generating the check PDF.

PrintChecksProps

Props for PrintChecks.

Property	Type	Description
companyId	string	Identifier of the company that owns the payroll.
payrollId	string	Identifier of the payroll to generate printable checks for.
onEvent?	OnEventType<EventType, unknown>	Callback invoked each time the component emits an event.

Inherits children, className, defaultValues, dictionary, FallbackComponent, LoaderComponent from Omit.

Events

Event	Description	Data
payroll/printChecks/start	User opened the print-checks modal from the banner	—
payroll/printChecks/generate/start	User submitted the print-checks form	—
payroll/printChecks/generate/succeeded	Printable checks finished generating	{ documentUrl }
payroll/printChecks/generate/failed	The print-checks request was rejected or generation failed	{ errorMessage }
payroll/printChecks/retry	User retried after a failed generation	—
payroll/printChecks/cancel	User cancelled the print-checks form	—
payroll/printChecks/close	User closed the failure or summary screen	—

Endpoints

Method	Path
GET	/v1/companies/:companyId/payrolls/:payrollId
GET	/v1/generated_documents/:documentType/:requestUuid
POST	/v1/payrolls/:payrollUuid/generated_documents/printable_payroll_checks

---

RecoveryCases

Displays open recovery cases for a company and provides an in-modal resubmit workflow for resolving them.

Remarks

Recovery cases are issues that surface after a payroll has been submitted (for example, a returned ACH transfer) and must be resolved before subsequent payrolls can run cleanly. This component is also embedded inside PayrollBlockerList, but can be used standalone when you want a dedicated recovery cases surface.

RecoveryCasesProps

Props for RecoveryCases.

Property	Type	Description
companyId	string	UUID of the company whose recovery cases should be listed.
onEvent?	OnEventType<EventType, unknown>	Callback invoked each time the component emits an event.

Inherits children, className, defaultValues, dictionary, FallbackComponent, LoaderComponent from Omit.

Events

Event	Description	Data
recoveryCase/resolve	User opens the resubmit modal for a recovery case	{ recoveryCaseId: string }
recoveryCase/resubmit/done	User successfully resubmits a recovery case	Resubmit result payload
recoveryCase/resubmit/cancel	User cancels the resubmit modal	—

Endpoints

Method	Path
GET	/v1/companies/:companyUuid/recovery_cases
PUT	/v1/recovery_cases/:recoveryCaseUuid/redebit

---

TransitionCreation

Creation form for transition payrolls covering the gap between an old and new pay schedule.

Displays the transition pay period and pay schedule information, and collects a check date, deduction preference, and tax withholding configuration before submitting the resulting off-cycle payroll for execution.

TransitionCreationProps

Props for the TransitionCreation component.

Property	Type	Description
companyId	string	The associated company identifier.
endDate	string	The end date of the transition pay period (YYYY-MM-DD).
onEvent	OnEventType<EventType, unknown>	Callback invoked each time the component emits an event — user interactions, successful API responses, step transitions, or errors. Receives the event type constant and an optional payload whose shape varies by event. See the Event Handling guide and each component's event table for the full list of emitted events.
payScheduleUuid	string	The UUID of the pay schedule this transition is associated with.
startDate	string	The start date of the transition pay period (YYYY-MM-DD).
dictionary?	Record<"en", DeepPartial<PayrollTransitionCreation>>	Overrides for the component's i18n strings. Supply a partial object whose keys match the component's resource namespace — any omitted keys fall back to SDK defaults. See the Translation guide for details.

Inherits children, className, defaultValues, FallbackComponent, LoaderComponent from BaseComponentInterface.

Events

Event	Description	Data
transition/created	The transition payroll has been created	{ payrollUuid: string }

The check date must be at least the company's ACH lead time (typically two business days) from today. Deductions default to included and tax withholding defaults to the regular rate with an every-other-week pay period.

Endpoints

Method	Path
GET	/v1/companies/:companyId/pay_schedules
POST	/v1/companies/:companyId/payrolls
GET	/v1/companies/:companyUuid/payment_configs

---

TransitionPayroll

Resolves and runs a transition payroll for a pay-schedule change, picking up an existing unprocessed transition payroll when one exists and creating one otherwise.

Remarks

A transition payroll covers the gap that opens when a company changes its pay schedule. This component looks up whether one already exists for the pay period and picks the starting screen:

• If it exists, it starts on PayrollConfiguration for that payroll.
• Otherwise it starts on TransitionCreation, then advances to PayrollConfiguration once the payroll is created.

Configuration events (calculate, employee edit, blockers, etc.) are emitted through onEvent for the host to route. Compose it inside TransitionFlow for the full run-payroll experience, or handle the events yourself.

Example

App.tsx

import { Payroll, type EventType } from '@gusto/embedded-react-sdk'

function MyApp() {
  return (
    <Payroll.TransitionPayroll
      companyId="a007e1ab-3595-43c2-ab4b-af7a5af2e365"
      startDate="2025-01-16"
      endDate="2025-01-31"
      payScheduleUuid="c75c1ef6-2ec0-4cca-94a5-8b4cf7e5ea21"
      onEvent={(eventType: EventType) => {
        if (eventType === 'runPayroll/calculated') {
          // Payroll calculated — navigate to your review screen
        }
      }}
    />
  )
}

TransitionPayrollProps

Props for TransitionPayroll.

Property	Type	Description
companyId	string	The company running the transition payroll.
endDate	string	The end date of the transition pay period (YYYY-MM-DD).
onEvent	OnEventType<EventType, unknown>	Callback invoked each time the component emits an event — user interactions, successful API responses, step transitions, or errors. Receives the event type constant and an optional payload whose shape varies by event. See the Event Handling guide and each component's event table for the full list of emitted events.
payScheduleUuid	string	The UUID of the pay schedule the transition is associated with.
startDate	string	The start date of the transition pay period (YYYY-MM-DD).
dictionary?	Record<"en", DeepPartial<common>> | Record<"en", DeepPartial<CompanyAddresses>> | Record<"en", DeepPartial<CompanyAssignSignatory>> | Record<"en", DeepPartial<CompanyBankAccount>> | Record<"en", DeepPartial<CompanyDocumentList>> | Record<"en", DeepPartial<CompanyFederalTaxes>> | Record<"en", DeepPartial<CompanyIndustry>> | Record<"en", DeepPartial<CompanyLocations>> | Record<"en", DeepPartial<CompanyManagementAutoPilotDialog>> | Record<"en", DeepPartial<CompanyManagementPaySchedule>> | Record<"en", DeepPartial<CompanyManagementPayScheduleAssignment>> | Record<"en", DeepPartial<CompanyManagementTaxPaymentDetail>> | Record<"en", DeepPartial<CompanyManagementTaxPaymentsList>> | Record<"en", DeepPartial<CompanyOnboardingOverview>> | Record<"en", DeepPartial<CompanyPaySchedule>> | Record<"en", DeepPartial<CompanySignatureForm>> | Record<"en", DeepPartial<CompanyStateTaxes>> | Record<"en", DeepPartial<CompanyTimeOffCreateTimeOffPolicy>> | Record<"en", DeepPartial<CompanyTimeOffEmployeeTable>> | Record<"en", DeepPartial<CompanyTimeOffHolidayPolicy>> | Record<"en", DeepPartial<CompanyTimeOffPolicyDetail>> | Record<"en", DeepPartial<CompanyTimeOffSelectEmployees>> | Record<"en", DeepPartial<CompanyTimeOffSelectPolicyType>> | Record<"en", DeepPartial<CompanyTimeOffTimeOffPolicies>> | Record<"en", DeepPartial<CompanyTimeOffTimeOffPolicyDetails>> | Record<"en", DeepPartial<CompanyTimeOffTimeOffRequests>> | Record<"en", DeepPartial<ContractorAddress>> | Record<"en", DeepPartial<ContractorBankAccountFields>> | Record<"en", DeepPartial<ContractorContractorList>> | Record<"en", DeepPartial<ContractorDashboard>> | Record<"en", DeepPartial<ContractorDismissal>> | Record<"en", DeepPartial<ContractorDocumentsList>> | Record<"en", DeepPartial<ContractorLanding>> | Record<"en", DeepPartial<ContractorManagementAddress>> | Record<"en", DeepPartial<ContractorManagementCompensation>> | Record<"en", DeepPartial<ContractorManagementDocuments>> | Record<"en", DeepPartial<ContractorManagementPaymentMethod>> | Record<"en", DeepPartial<ContractorManagementProfile>> | Record<"en", DeepPartial<ContractorManagementContractorList>> | Record<"en", DeepPartial<ContractorNewHireReport>> | Record<"en", DeepPartial<ContractorOnboardingSummary>> | Record<"en", DeepPartial<ContractorPaymentMethod>> | Record<"en", DeepPartial<ContractorPaymentsCreateHistoricalPayment>> | Record<"en", DeepPartial<ContractorPaymentsCreatePayment>> | Record<"en", DeepPartial<ContractorPaymentsHistoricalPaymentSummary>> | Record<"en", DeepPartial<ContractorPaymentsPaymentHistory>> | Record<"en", DeepPartial<ContractorPaymentsPaymentStatement>> | Record<"en", DeepPartial<ContractorPaymentsPaymentSummary>> | Record<"en", DeepPartial<ContractorPaymentsPaymentsList>> | Record<"en", DeepPartial<ContractorProfile>> | Record<"en", DeepPartial<ContractorSelectContractors>> | Record<"en", DeepPartial<ContractorSignatureForm>> | Record<"en", DeepPartial<ContractorSubmit>> | Record<"en", DeepPartial<EmployeeBankAccount>> | Record<"en", DeepPartial<EmployeeBankFormBody>> | Record<"en", DeepPartial<EmployeeCompensation>> | Record<"en", DeepPartial<EmployeeDashboard>> | Record<"en", DeepPartial<EmployeeDeductions>> | Record<"en", DeepPartial<EmployeeDeductionsForm>> | Record<"en", DeepPartial<EmployeeDocumentManager>> | Record<"en", DeepPartial<EmployeeDocumentSigner>> | Record<"en", DeepPartial<EmployeeEmployeeDocuments>> | Record<"en", DeepPartial<EmployeeEmployeeList>> | Record<"en", DeepPartial<EmployeeEmploymentEligibility>> | Record<"en", DeepPartial<EmployeeFederalTaxes>> | Record<"en", DeepPartial<EmployeeFederalTaxesView>> | Record<"en", DeepPartial<EmployeeHomeAddress>> | Record<"en", DeepPartial<EmployeeI9SignatureForm>> | Record<"en", DeepPartial<EmployeeLanding>> | Record<"en", DeepPartial<EmployeeManagementCompensation>> | Record<"en", DeepPartial<EmployeeManagementDeductions>> | Record<"en", DeepPartial<EmployeeManagementDocuments>> | Record<"en", DeepPartial<EmployeeManagementFederalTaxes>> | Record<"en", DeepPartial<EmployeeManagementHomeAddress>> | Record<"en", DeepPartial<EmployeeManagementPaymentMethod>> | Record<"en", DeepPartial<EmployeeManagementPaymentMethodBankForm>> | Record<"en", DeepPartial<EmployeeManagementPaymentMethodSplitForm>> | Record<"en", DeepPartial<EmployeeManagementPaystubs>> | Record<"en", DeepPartial<EmployeeManagementProfile>> | Record<"en", DeepPartial<EmployeeManagementStateTaxes>> | Record<"en", DeepPartial<EmployeeManagementWorkAddress>> | Record<"en", DeepPartial<EmployeeManagementEmployeeList>> | Record<"en", DeepPartial<EmployeeOnboardingSummary>> | Record<"en", DeepPartial<EmployeePaySchedules>> | Record<"en", DeepPartial<EmployeePaymentMethod>> | Record<"en", DeepPartial<EmployeeProfile>> | Record<"en", DeepPartial<EmployeeSplitPaycheck>> | Record<"en", DeepPartial<EmployeeSplitPaymentsFormBody>> | Record<"en", DeepPartial<EmployeeStateTaxes>> | Record<"en", DeepPartial<EmployeeStateTaxesView>> | Record<"en", DeepPartial<EmployeeTerminationsTerminateEmployee>> | Record<"en", DeepPartial<EmployeeTerminationsTerminationFlow>> | Record<"en", DeepPartial<EmployeeTerminationsTerminationSummary>> | Record<"en", DeepPartial<InformationRequestsInformationRequestForm>> | Record<"en", DeepPartial<InformationRequestsInformationRequestList>> | Record<"en", DeepPartial<InformationRequests>> | Record<"en", DeepPartial<PayrollCommon>> | Record<"en", DeepPartial<PayrollConfirmWireDetailsBanner>> | Record<"en", DeepPartial<PayrollConfirmWireDetailsForm>> | Record<"en", DeepPartial<PayrollDismissal>> | Record<"en", DeepPartial<PayrollEmployeeSelection>> | Record<"en", DeepPartial<PayrollGrossUpModal>> | Record<"en", DeepPartial<PayrollOffCycle>> | Record<"en", DeepPartial<PayrollOffCycleCreation>> | Record<"en", DeepPartial<PayrollOffCycleDeductionsSetting>> | Record<"en", DeepPartial<PayrollOffCyclePayPeriodDateForm>> | Record<"en", DeepPartial<PayrollOffCycleReasonSelection>> | Record<"en", DeepPartial<PayrollOffCycleTaxWithholding>> | Record<"en", DeepPartial<PayrollPayrollBlocker>> | Record<"en", DeepPartial<PayrollPayrollConfiguration>> | Record<"en", DeepPartial<PayrollPayrollEditEmployee>> | Record<"en", DeepPartial<PayrollPayrollFlow>> | Record<"en", DeepPartial<PayrollPayrollHistory>> | Record<"en", DeepPartial<PayrollPayrollLanding>> | Record<"en", DeepPartial<PayrollPayrollList>> | Record<"en", DeepPartial<PayrollPayrollOverview>> | Record<"en", DeepPartial<PayrollPayrollReceipts>> | Record<"en", DeepPartial<PayrollPrintChecksBanner>> | Record<"en", DeepPartial<PayrollPrintChecksFailure>> | Record<"en", DeepPartial<PayrollPrintChecksForm>> | Record<"en", DeepPartial<PayrollPrintChecksSummary>> | Record<"en", DeepPartial<PayrollRecoveryCasesList>> | Record<"en", DeepPartial<PayrollRecoveryCasesResubmit>> | Record<"en", DeepPartial<PayrollTransition>> | Record<"en", DeepPartial<PayrollTransitionCreation>> | Record<"en", DeepPartial<PayrollTransitionPayrollAlert>> | Record<"en", DeepPartial<PayrollUNSTABLE_PayrollEditEmployee>> | Record<"en", DeepPartial<PayrollWireInstructions>>	Overrides for the component's i18n strings. Supply a partial object whose keys match the component's resource namespace — any omitted keys fall back to SDK defaults. See the Translation guide for details.
payrollUuid?	string	UUID of an existing transition payroll. When provided, the component skips the lookup and starts on configuration for this payroll. When omitted, it resolves the payroll for the pay period.
withReimbursements?	boolean	Whether reimbursement fields are shown on the configuration screen. Defaults to true.

Inherits children, className, defaultValues, FallbackComponent, LoaderComponent from BaseComponentInterface.

Events

Event	Description	Data
transition/created	The transition payroll has been created and the flow advances to configuration	{ payrollUuid: string }

Once configuration begins, all standard run-payroll events are emitted as well (e.g. runPayroll/calculated, runPayroll/employee/edit, runPayroll/blockers/viewAll).

Components

• TransitionCreation
• PayrollConfiguration

Endpoints

Method	Path
GET	/v1/companies/:companyId/payrolls

---

Utility types

ApiPayrollBlocker

A single payroll blocker entry: an issue that must be resolved before a payroll can be calculated or submitted (for example, missing employee information, invalid tax setups, or incomplete company configuration).

Properties

Property	Type	Description
key	string	Stable identifier for the blocker type, used to look up display copy and behavior.
message?	string	Human-readable message describing the blocker, when provided by the API.

---

ConfirmWireDetailsComponentType

ConfirmWireDetailsComponentType = ComponentType<ConfirmWireDetailsProps>

Component type matching the ConfirmWireDetails signature.

Use this when supplying a custom wire-confirmation UI to a payroll flow via a ConfirmWireDetailsComponent prop.

---

OffCycleCreationFormData

Form values collected by the OffCycleCreation component.

Extends

• OffCyclePayPeriodDateFormData

Properties

Property	Type	Description
checkDate	Date | null	Date employees will be paid; must be at least the company's ACH lead time of business days from today for direct deposit, unless isCheckOnly is true.
endDate	Date | null	End of the pay period; required unless isCheckOnly is true, and must be on or after startDate.
includeAllEmployees	boolean	When true, every onboarded active employee is included in the payroll.
isCheckOnly	boolean	When true, all employees are paid by check rather than direct deposit; start and end dates become optional and the check date may be today or any future date.
reason	OffCycleReason	The off-cycle reason — 'bonus' or 'correction'.
selectedEmployeeUuids	string[]	Employee UUIDs to include. Only consulted when includeAllEmployees is false.
skipRegularDeductions	boolean	When true, regular deductions are skipped for this payroll.
startDate	Date | null	Beginning of the pay period; required unless isCheckOnly is true, and must be on or before endDate.

---

OffCycleDeductionsSettingChangePayload

Payload emitted by OffCycleDeductionsSetting on the offCycle/deductionsChange event.

Properties

Property	Type	Description
skipRegularDeductions	boolean	Whether the user selected to skip regular deductions.

---

OffCyclePayPeriodDateFormData

Pay-period date selections collected for an off-cycle payroll.

Extended by

• OffCycleCreationFormData

Properties

Property	Type	Description
checkDate	Date | null	Date employees will be paid; must be at least the company's ACH lead time of business days from today for direct deposit, unless isCheckOnly is true.
endDate	Date | null	End of the pay period; required unless isCheckOnly is true, and must be on or after startDate.
isCheckOnly	boolean	When true, all employees are paid by check rather than direct deposit; start and end dates become optional and the check date may be today or any future date.
startDate	Date | null	Beginning of the pay period; required unless isCheckOnly is true, and must be on or before endDate.

---

OffCyclePayrollDateType

OffCyclePayrollDateType = "bonus" | "correction"

Off-cycle payroll reason, used to pick default withholding/deduction settings.

Remarks

'bonus' is used for paying a bonus, gift, or commission. 'correction' is used for running a correction payment. Legacy gws-flows treats both identically for pay-period date validation -- see createOffCyclePayPeriodDateFormSchema, which no longer branches on this type.

---

OffCycleReason

OffCycleReason = "bonus" | "correction"

Reason for running an off-cycle payroll.

bonus covers bonuses, gifts, or commissions; correction covers any payroll run outside the regular pay schedule.

---

OffCycleReasonDefaults

Recommended deduction and withholding defaults paired with an off-cycle reason.

Properties

Property	Type	Description
skipDeductions	boolean	Whether regular deductions and contributions should be skipped for this payroll.
withholdingType	WithholdingType	Withholding rate to apply for this payroll.

---

PayrollExecutionInitialState

PayrollExecutionInitialState = "configuration" | "overview"

Entry point for PayrollExecutionFlow. Determines which screen the flow renders first.

---

PayrollFlowAlert

PayrollFlowAlert = object

An alert banner rendered above payroll content in PayrollOverview and PayrollConfiguration.

Properties

Property	Type	Description
title	string	Short heading text displayed in the alert.
type	"error" | "info" | "success"	Visual severity of the alert.
alertKey?	string	Stable key used to track alert identity across renders (e.g. for animations or deduplication).
content?	ReactNode	Optional body content rendered below the title.
onDismiss?	() => void	Called when the user dismisses the alert. When omitted, the alert is not dismissible.

---

SelectReasonPayload

Payload emitted with the offCycle/selectReason event when a reason is chosen.

Properties

Property	Type	Description
defaults	OffCycleReasonDefaults	Recommended deduction and withholding defaults for the selected reason.
reason	OffCycleReason	The reason the user selected.

---

TransitionCreationFormData

Form values collected by the TransitionCreation component.

Properties

Property	Type	Description
checkDate	Date | null	The date employees will be paid. Must be at least the company's ACH lead time from today.
skipRegularDeductions	boolean	When true, regular deductions are skipped for this payroll.

---

WithholdingType

WithholdingType = "supplemental" | "regular"

Tax withholding rate applied to an off-cycle payroll.

supplemental applies the IRS supplemental withholding rate; regular applies the employee's regular withholding rate.