usePaymentMethodForm

usePaymentMethodForm(props: UsePaymentMethodFormProps): HookLoadingResult | UsePaymentMethodFormReady

Headless React Hook Form hook for updating an employee's payment method.

Remarks

Switches between Direct Deposit and Check. Always operates in update mode — every employee has a payment method, defaulting to Check. Switching to Check sends a minimal request body; switching to or staying on Direct Deposit preserves the existing splits and version so split allocations are not lost when only the type changes.

Example

Example

import {
  usePaymentMethodForm,
  SDKFormProvider,
  PAYMENT_METHODS,
  type PaymentMethodType,
} from '@gusto/embedded-react-sdk'

function PaymentMethodScreen({ employeeId }: { employeeId: string }) {
  const paymentMethodForm = usePaymentMethodForm({ employeeId })

  if (paymentMethodForm.isLoading) return null
  const { Fields } = paymentMethodForm.form

  return (
    <SDKFormProvider formHookResult={paymentMethodForm}>
      <form
        onSubmit={e => {
          e.preventDefault()
          void paymentMethodForm.actions.onSubmit()
        }}
      >
        <Fields.Type
          label="Select payment method"
          getOptionLabel={(value: PaymentMethodType) =>
            value === PAYMENT_METHODS.directDeposit ? 'Direct Deposit' : 'Check'
          }
        />
        <button type="submit" disabled={paymentMethodForm.status.isPending}>Save</button>
      </form>
    </SDKFormProvider>
  )
}

Props

UsePaymentMethodFormProps

Props for usePaymentMethodForm.

Property	Type	Description
employeeId	string	Employee whose payment method is being edited.
defaultValues?	Partial<PaymentMethodFormData>	Pre-fill form values. Server data (the current payment method) is used when no override is supplied.
optionalFieldsToRequire?	PaymentMethodFormOptionalFieldsToRequire	Override optional fields to be required. Reserved for future schema expansion — type is always required and always has a default.
shouldFocusError?	boolean	Auto-focus the first invalid field on submit. Set to false when using composeSubmitHandler. Defaults to true.
validationMode?	"onChange" | "onBlur" | "onSubmit" | "onTouched" | "all"	When validation runs. Passed through to react-hook-form. Defaults to 'onSubmit'.

Returns

HookLoadingResult | UsePaymentMethodFormReady

A loading-state result while the current payment method is loading, or a UsePaymentMethodFormReady once ready.

UsePaymentMethodFormResult

UsePaymentMethodFormResult = HookLoadingResult | UsePaymentMethodFormReady

Return type of usePaymentMethodForm — a discriminated union on isLoading.

---

UsePaymentMethodFormReady

Ready-state return value of usePaymentMethodForm.

Property	Type	Description
actions	object	Submit the form. Returns the updated payment method on success or undefined on validation/mutation failure.
actions.onSubmit	() => Promise<HookSubmitResult<EmployeePaymentMethod> | undefined>	-
data	object	The employee's current payment method, loaded from the API.
data.paymentMethod	EmployeePaymentMethod	-
errorHandling	HookErrorHandling	Error state and recovery actions.
form	object	Form bindings: pre-bound field components, per-field metadata, submission values, and react-hook-form internals.
form.Fields	PaymentMethodFormFields	-
form.fieldsMetadata	PaymentMethodFormFieldsMetadata	-
form.getFormSubmissionValues	() => PaymentMethodFormData | undefined	-
form.hookFormInternals	HookFormInternals<PaymentMethodFormData>	-
isLoading	false	Always false in this branch; discriminates from HookLoadingResult.
status	object	isPending reflects the in-flight update mutation; mode is always 'update'.
status.isPending	boolean	-
status.mode	"update"	-

Fields

PaymentMethodFormFields

Field components exposed by usePaymentMethodForm on form.Fields.

Property	Type	Description
Type	ComponentType<TypeFieldProps>	Bound to type.

---

Type

Bound to type.

<form.Fields.Type
  label="Type"
  validationMessages={{ REQUIRED: '…' }}
/>

TypeFieldProps

HookFieldProps<RadioGroupHookFieldProps<PaymentMethodFormRequiredValidation, PaymentMethodType>>

Props accepted by usePaymentMethodForm's Fields.Type component.

Property	Type	Description
label	string	Visible label rendered above the field.
FieldComponent?	ComponentType<RadioGroupProps>	Replaces the default radio group UI component; must accept the same props as RadioGroupProps.
getOptionLabel?	(entry: PaymentMethodType) => string	Maps a raw option entry to its display label; when omitted, options use the labels provided by the hook.
validationMessages?	ValidationMessages<PaymentMethodFormRequiredValidation>	Custom error text keyed by validation error code.

Also accepts description, formHookResult from RadioGroupHookFieldProps.

Validations

PaymentMethodFormRequiredValidation

PaymentMethodFormRequiredValidation = "REQUIRED"

Validation error codes emitted by usePaymentMethodForm fields that only emit REQUIRED.

Utility types

PAYMENT_METHOD_TYPES

const PAYMENT_METHOD_TYPES: readonly ["Direct Deposit", "Check"]

Supported payment method type values: direct deposit and check.

---

PaymentMethodFormData

Shape of the values managed by the payment method form.

Properties

Property	Type
type	"Check" | "Direct Deposit"

---

PaymentMethodFormErrorCode

PaymentMethodFormErrorCode = "REQUIRED"

Union of validation error code strings emitted by the payment method form schema.

---

PaymentMethodFormErrorCodes

const PaymentMethodFormErrorCodes: object

Validation error codes emitted by the payment method form schema. Map these codes to localized copy in validationMessages when composing the hook.

Type Declaration

Name	Type
REQUIRED	"REQUIRED"

---

PaymentMethodFormField

PaymentMethodFormField = "type"

Field names accepted by the payment method form.

---

PaymentMethodFormFieldsMetadata

Field	Type
type	FieldMetadataWithOptions<"Check" | "Direct Deposit">

Per-field metadata exposed on form.fieldsMetadata for usePaymentMethodForm.

---

PaymentMethodFormOptionalFieldsToRequire

PaymentMethodFormOptionalFieldsToRequire = OptionalFieldsToRequire<typeof requiredFieldsConfig>

Keys of optional payment method fields that can be promoted to required via the hook's optionalFieldsToRequire option.

---

PaymentMethodType

PaymentMethodType = "Check" | "Direct Deposit"

Union of payment method type values that the form accepts.

---

Endpoints

Method	Path
GET	/v1/employees/:employeeId/payment_method
PUT	/v1/employees/:employeeId/payment_method