Skip to main content

useContractorPaymentMethodForm

useContractorPaymentMethodForm(props: UseContractorPaymentMethodFormProps): HookLoadingResult | UseContractorPaymentMethodFormReady

Headless React Hook Form hook for managing a contractor's payment method type.

Remarks​

Owns only the payment method type selection (Direct Deposit or Check) and, on submit, updates the contractor's payment method via PUT. Always operates in update mode — every contractor has a payment method, defaulting to Check.

The bank account itself is managed by the separate useContractorBankAccountForm hook. On the Direct Deposit path the bank-account POST updates the payment method as a server side-effect, so a composing component submits the bank form instead of this hook; this hook's onSubmit is used for the Check path. status.isDirectDeposit lets the component drive that branching.

Example​

Example
import { useContractorPaymentMethodForm, SDKFormProvider } from '@gusto/embedded-react-sdk'

function PaymentTypeScreen({ contractorId }: { contractorId: string }) {
  const paymentMethod = useContractorPaymentMethodForm({ contractorId })

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

  return (
    <SDKFormProvider formHookResult={paymentMethod}>
      <form
        onSubmit={e => {
          e.preventDefault()
          void paymentMethod.actions.onSubmit()
        }}
      >
        <Fields.Type label="Select payment method" />
        <button type="submit" disabled={paymentMethod.status.isPending}>Save</button>
      </form>
    </SDKFormProvider>
  )
}

Props​

UseContractorPaymentMethodFormProps​

Props for useContractorPaymentMethodForm.

PropertyTypeDescription
contractorIdstringContractor whose payment method is being edited.
defaultValues?Partial<ContractorPaymentMethodFormData>Pre-fill form values. Server data (the current payment method) is used when no override is supplied.
shouldFocusError?booleanAuto-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 | UseContractorPaymentMethodFormReady

A loading-state result while data loads, or a UseContractorPaymentMethodFormReady once ready.

UseContractorPaymentMethodFormResult​

UseContractorPaymentMethodFormResult = HookLoadingResult | UseContractorPaymentMethodFormReady

Return type of useContractorPaymentMethodForm — a discriminated union on isLoading.

UseContractorPaymentMethodFormReady​

Ready-state return value of useContractorPaymentMethodForm.

PropertyTypeDescription
actionsobjectSubmit the form. Returns the updated payment method on success or undefined on validation/mutation failure.
actions.onSubmit() => Promise<HookSubmitResult<ContractorPaymentMethod> | undefined>-
dataobjectThe contractor's current payment method, loaded from the API.
data.paymentMethodContractorPaymentMethod-
errorHandlingHookErrorHandlingError state and recovery actions.
formobjectForm bindings: pre-bound field components, per-field metadata, submission values, and react-hook-form internals.
form.FieldsContractorPaymentMethodFormFields-
form.fieldsMetadataContractorPaymentMethodFieldsMetadata-
form.getFormSubmissionValues() => ContractorPaymentMethodFormData | undefined-
form.hookFormInternalsHookFormInternals<ContractorPaymentMethodFormData>-
isLoadingfalseAlways false in this branch; discriminates from HookLoadingResult.
statusobjectisPending reflects the in-flight update mutation; mode is always 'update'. isDirectDeposit reflects the currently selected type so a composing component can render bank fields and decide whether to submit the bank-account form.
status.isDirectDepositboolean-
status.isPendingboolean-
status.mode"update"-

Fields​

ContractorPaymentMethodFormFields​

Field components exposed by useContractorPaymentMethodForm on form.Fields.

PropertyTypeDescription
TypeComponentType<TypeFieldProps>Radio group bound to type. Selects whether the contractor is paid by Direct Deposit or Check. Supply getOptionLabel to translate the option labels.

Type​

Radio group bound to type. Selects whether the contractor is paid by Direct Deposit or Check. Supply getOptionLabel to translate the option labels.

<form.Fields.Type label="Type" />

ContractorPaymentMethodTypeFieldProps​

HookFieldProps<RadioGroupHookFieldProps<never, ContractorPaymentMethodFormType>>

Props accepted by useContractorPaymentMethodForm's Fields.Type component.

PropertyTypeDescription
labelstringVisible label rendered above the field.
FieldComponent?ComponentType<RadioGroupProps>Replaces the default radio group UI component; must accept the same props as RadioGroupProps.
getOptionLabel?(entry: ContractorPaymentMethodFormType) => stringMaps a raw option entry to its display label; when omitted, options use the labels provided by the hook.

Also accepts description, formHookResult from RadioGroupHookFieldProps.

Utility types​

ContractorPaymentMethodErrorCode​

ContractorPaymentMethodErrorCode = "REQUIRED"

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

ContractorPaymentMethodErrorCodes​

const ContractorPaymentMethodErrorCodes: object

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

Type Declaration​

NameType
REQUIRED"REQUIRED"

ContractorPaymentMethodFieldsMetadata​

FieldType
typeFieldMetadataWithOptions<ContractorPaymentMethodFormType>

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

ContractorPaymentMethodFormData​

Shape of the values managed by the contractor payment method form.

Properties​

PropertyType
type"Check" | "Direct Deposit"

ContractorPaymentMethodFormField​

ContractorPaymentMethodFormField = "type"

Field names accepted by the contractor payment method form.

ContractorPaymentMethodFormType​

ContractorPaymentMethodFormType = "Check" | "Direct Deposit"

Union of payment method type values that the form accepts.

Endpoints​

MethodPath
GET/v1/contractors/:contractorUuid/payment_method
PUT/v1/contractors/:contractorUuid/payment_method