PaymentFlow

Hub for creating and managing contractor payments for a company.

Payment Workflow

The typical step sequence when composing the blocks manually:

1. PaymentsList — browse existing payment groups and start a new one.
2. CreatePayment — select a date, edit per-contractor amounts, preview, and submit. Handles Fast ACH blockers and wire transfer requirements inline.
3. PaymentSummary — review the created group, debit details, and wire instructions when required.
4. PaymentHistory — inspect a payment group's details and cancel individual payments.
5. PaymentStatement — see the full breakdown for one contractor's payment.

Remarks

Composes the contractor payment blocks into a complete experience with breadcrumb navigation between the payments list, the create-payment form, the post-creation summary, the payment-history detail view, and individual contractor payment statements. Also routes into the information-requests flow when a payment-related request needs a response, and surfaces wire-transfer confirmation alerts after a wire details submission.

Events emitted by the blocks bubble up through the single onEvent handler.

Example

App.tsx

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

function MyApp() {
  return (
    <ContractorManagement.PaymentFlow
      companyId="a007e1ab-3595-43c2-ab4b-af7a5af2e365"
      onEvent={() => {}}
    />
  )
}

PaymentFlowProps

Props for PaymentFlow.

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.

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

Events

Event	Description	Data
contractor/payments/create	Fired when the user chooses to create a new payment	—
contractor/payments/created	Fired when a payment group is successfully created	The created ContractorPaymentGroup
contractor/payments/view	Fired when the user selects a payment group to view	{ paymentId: string }
contractor/payments/view/details	Fired when the user views a specific contractor payment	{ contractor: Contractor, paymentGroupId: string }
contractor/payments/cancel	Fired when a payment is cancelled	{ paymentId: string }
contractor/payments/exit	Fired when the user completes the payment flow	`{ uuid?: string
contractor/payments/rfi/respond	Fired when the user clicks to respond to a pending information request	—
payroll/wire/form/done	Fired when wire transfer details are submitted	{ wireInRequest: WireInRequest, confirmationAlert: { title: string, content?: string } }
informationRequest/form/done	Fired when the information-requests flow completes	—
informationRequest/form/cancel	Fired when the information-requests flow is cancelled	—
breadcrumb/navigate	Fired when the user clicks a breadcrumb to navigate back	{ key: string, onNavigate: (ctx) => ctx }

Sub-components

Component	Description
PaymentsList	Displays a list of contractor payment groups for a company.
CreatePayment	Form for creating a contractor payment group, including date selection, per-contractor edits, preview, and submission blockers.
PaymentSummary	Displays a summary of a created contractor payment group, including payment totals, debit information, contractor details, and wire transfer instructions when required.
PaymentHistory	Displays a contractor payment group, including each individual contractor payment, with actions to view details or cancel.
PaymentStatement	Displays a single contractor's payment statement within a payment group, including wage breakdown, bonuses, reimbursements, and a receipt card for funded direct-deposit payments.
InformationRequests.InformationRequestsFlow	Hub for viewing and responding to outstanding information requests from Gusto.

Step flow

The flow is a hub-and-spoke loop with no terminal state — the payments list is the landing screen, and every path returns to it:

• Create a payment — PaymentsList → CreatePayment → PaymentSummary, then back to the list.
• View history — PaymentsList → PaymentHistory → PaymentStatement; the history view can also cancel a payment and return to the list.
• Respond to a request — PaymentsList opens the embedded InformationRequestsFlow, returning to the list once the request is submitted or cancelled.

Breadcrumbs navigate back to any prior step, and submitting wire-transfer details surfaces a success alert on the list and summary screens. The diagram below shows the topology; the event behind each transition is listed in the events table above.

Important Notes

Payment Timing

• Direct deposit payments submitted before 4pm PT on a business day take 2 business days to complete
• Fast ACH (2-day) payments have threshold limits; exceeding the threshold requires wire transfer or switching to 4-day processing

Payment Requirements

• Only active contractors with completed onboarding can receive payments
• At least one contractor payment must be included in a payment group
• Bank account must be set up for the company to process payments

Submission Blockers

Payment submission may be blocked by:

• Fast ACH Threshold Exceeded: Payment amount exceeds the fast ACH limit
  • Options: Wire transfer (fastest) or switch to 4-day direct deposit
• Needs Earned Access for Fast ACH: Company hasn't earned access to faster payments yet
  • Must use standard 4-day processing

Wire Transfers

When wire transfer is required:

• Instructions are provided in the payment flow
• Must be completed by specified deadline to ensure timely payment
• Confirmation workflow tracks wire transfer submission

Endpoints

Method	Path
GET	/v1/companies/:companyId/bank_accounts
GET	/v1/companies/:companyId/contractor_payment_groups
POST	/v1/companies/:companyId/contractor_payment_groups
POST	/v1/companies/:companyId/contractor_payment_groups/preview
DELETE	/v1/companies/:companyId/contractor_payments/:contractorPaymentId
GET	/v1/companies/:companyUuid/contractors
GET	/v1/companies/:companyUuid/information_requests
GET	/v1/companies/:companyUuid/payment_configs
GET	/v1/contractor_payment_groups/:contractorPaymentGroupUuid
GET	/v1/contractor_payments/:contractorPaymentUuid/receipt
PUT	/v1/information_requests/:informationRequestUuid/submit