Skip to main content

useContractorBankAccountForm

useContractorBankAccountForm(props: UseContractorBankAccountFormProps): HookLoadingResult | UseContractorBankAccountFormReady

Headless React Hook Form hook for creating a contractor's bank account.

Remarks​

Captures the account nickname, routing number, account number, and account type. Creating a bank account also updates the contractor's payment method to Direct Deposit on the Gusto API as a side-effect, so the Direct Deposit path needs only this submit — no separate payment method update.

When the contractor already has a bank account on file, the account number field is pre-filled with the masked token the API returns (e.g. "XXXX1207"). The API requires account_number on every write and treats that exact masked value as "keep the existing account," so submitting it unchanged preserves the account while still applying any name/routing/type edits; typing a real number replaces it.

Example​

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

function AddBankAccount({ contractorId }: { contractorId: string }) {
  const bankForm = useContractorBankAccountForm({ contractorId })

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

  return (
    <SDKFormProvider formHookResult={bankForm}>
      <form
        onSubmit={e => {
          e.preventDefault()
          void bankForm.actions.onSubmit()
        }}
      >
        <Fields.Name label="Account nickname" />
        <Fields.RoutingNumber label="Routing number" />
        <Fields.AccountNumber label="Account number" />
        <Fields.AccountType label="Account type" />
        <button type="submit" disabled={bankForm.status.isPending}>Save</button>
      </form>
    </SDKFormProvider>
  )
}

Props​

UseContractorBankAccountFormProps​

Props for useContractorBankAccountForm.

PropertyTypeDescription
contractorIdstringContractor for whom to create the bank account.
defaultValues?Partial<ContractorBankAccountFormData>Pre-fill form values. The contractor's existing bank account is used when no override is supplied.
optionalFieldsToRequire?ContractorBankAccountOptionalFieldsToRequireOverride optional fields to be required.
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 | UseContractorBankAccountFormReady

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

UseContractorBankAccountFormResult​

UseContractorBankAccountFormResult = HookLoadingResult | UseContractorBankAccountFormReady

Return type of useContractorBankAccountForm — a discriminated union on isLoading.

UseContractorBankAccountFormReady​

Ready-state return value of useContractorBankAccountForm.

PropertyTypeDescription
actionsobjectSubmit the form. Returns the created bank account on success or undefined on validation/mutation failure.
actions.onSubmit() => Promise<HookSubmitResult<ContractorBankAccount> | undefined>-
dataobjectThe contractor's current bank account, loaded from the API, if any.
data.bankAccountContractorBankAccount | undefined-
errorHandlingHookErrorHandlingError state and recovery actions.
formobjectForm bindings: pre-bound field components, per-field metadata, submission values, and react-hook-form internals.
form.FieldsContractorBankAccountFormFields-
form.fieldsMetadataContractorBankAccountFieldsMetadata-
form.getFormSubmissionValues() => ContractorBankAccountFormData | undefined-
form.hookFormInternalsHookFormInternals<ContractorBankAccountFormData>-
isLoadingfalseAlways false in this branch; discriminates from HookLoadingResult.
statusobjectisPending reflects the in-flight create mutation; mode is always 'create'.
status.isPendingboolean-
status.mode"create"-

Fields​

ContractorBankAccountFormFields​

Field components exposed by useContractorBankAccountForm on form.Fields.

PropertyTypeDescription
AccountNumberComponentType<AccountNumberFieldProps>Bound to accountNumber. Pre-filled with the masked account number (e.g. "XXXX1207"), which is accepted unchanged to keep the existing account; a newly entered value is validated against the 1–17 digit numeric pattern.
AccountTypeComponentType<AccountTypeFieldProps>Bound to accountType. Options are Checking and Savings; defaults to Checking. Supply getOptionLabel to translate the option labels.
NameComponentType<NameFieldProps>Bound to name. Captures the bank account nickname.
RoutingNumberComponentType<RoutingNumberFieldProps>Bound to routingNumber. Validated against a 9-digit numeric pattern.

AccountNumber​

Bound to accountNumber. Pre-filled with the masked account number (e.g. "XXXX1207"), which is accepted unchanged to keep the existing account; a newly entered value is validated against the 1–17 digit numeric pattern.

<form.Fields.AccountNumber
  label="Account number"
  validationMessages={{ REQUIRED: '…', INVALID_ACCOUNT_NUMBER: '…' }}
/>

ContractorBankAccountAccountNumberFieldProps​

HookFieldProps<TextInputHookFieldProps<ContractorBankAccountAccountNumberValidation>>

Props accepted by useContractorBankAccountForm's Fields.AccountNumber component.

PropertyTypeDescription
labelstringVisible label rendered above the field.
FieldComponent?ComponentType<TextInputProps>Replaces the default text input UI component; must accept the same props as TextInputProps.
validationMessages?ValidationMessages<ContractorBankAccountAccountNumberValidation>Custom error text keyed by validation error code.

Also accepts description, formHookResult, placeholder, transform from TextInputHookFieldProps.

AccountType​

Bound to accountType. Options are Checking and Savings; defaults to Checking. Supply getOptionLabel to translate the option labels.

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

ContractorBankAccountAccountTypeFieldProps​

HookFieldProps<RadioGroupHookFieldProps<ContractorBankAccountRequiredValidation, ContractorAccountType>>

Props accepted by useContractorBankAccountForm's Fields.AccountType 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: ContractorAccountType) => stringMaps a raw option entry to its display label; when omitted, options use the labels provided by the hook.
validationMessages?ValidationMessages<ContractorBankAccountRequiredValidation>Custom error text keyed by validation error code.

Also accepts description, formHookResult from RadioGroupHookFieldProps.

Name​

Bound to name. Captures the bank account nickname.

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

ContractorBankAccountNameFieldProps​

HookFieldProps<TextInputHookFieldProps<ContractorBankAccountRequiredValidation>>

Props accepted by useContractorBankAccountForm's Fields.Name component.

PropertyTypeDescription
labelstringVisible label rendered above the field.
FieldComponent?ComponentType<TextInputProps>Replaces the default text input UI component; must accept the same props as TextInputProps.
validationMessages?ValidationMessages<ContractorBankAccountRequiredValidation>Custom error text keyed by validation error code.

Also accepts description, formHookResult, placeholder, transform from TextInputHookFieldProps.

RoutingNumber​

Bound to routingNumber. Validated against a 9-digit numeric pattern.

<form.Fields.RoutingNumber
  label="Routing number"
  validationMessages={{ REQUIRED: '…', INVALID_ROUTING_NUMBER: '…' }}
/>

ContractorBankAccountRoutingNumberFieldProps​

HookFieldProps<TextInputHookFieldProps<ContractorBankAccountRoutingNumberValidation>>

Props accepted by useContractorBankAccountForm's Fields.RoutingNumber component.

PropertyTypeDescription
labelstringVisible label rendered above the field.
FieldComponent?ComponentType<TextInputProps>Replaces the default text input UI component; must accept the same props as TextInputProps.
validationMessages?ValidationMessages<ContractorBankAccountRoutingNumberValidation>Custom error text keyed by validation error code.

Also accepts description, formHookResult, placeholder, transform from TextInputHookFieldProps.

Validations​

ContractorBankAccountAccountNumberValidation​

ContractorBankAccountAccountNumberValidation = "REQUIRED" | "INVALID_ACCOUNT_NUMBER"

Validation error codes emitted by the accountNumber field of useContractorBankAccountForm.

ContractorBankAccountRequiredValidation​

ContractorBankAccountRequiredValidation = "REQUIRED"

Validation error code emitted by useContractorBankAccountForm fields that only emit REQUIRED.

ContractorBankAccountRoutingNumberValidation​

ContractorBankAccountRoutingNumberValidation = "REQUIRED" | "INVALID_ROUTING_NUMBER"

Validation error codes emitted by the routingNumber field of useContractorBankAccountForm.

Utility types​

ContractorAccountType​

ContractorAccountType = "Checking" | "Savings"

Union of bank account type values that the form accepts.

ContractorBankAccountErrorCode​

ContractorBankAccountErrorCode = "REQUIRED" | "INVALID_ROUTING_NUMBER" | "INVALID_ACCOUNT_NUMBER"

Union of validation error code strings emitted by the contractor bank account form schema.

ContractorBankAccountErrorCodes​

const ContractorBankAccountErrorCodes: object

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

Type Declaration​

NameType
INVALID_ACCOUNT_NUMBER"INVALID_ACCOUNT_NUMBER"
INVALID_ROUTING_NUMBER"INVALID_ROUTING_NUMBER"
REQUIRED"REQUIRED"

ContractorBankAccountFieldsMetadata​

FieldType
accountNumberFieldMetadata
accountTypeFieldMetadataWithOptions<"Checking" | "Savings">
nameFieldMetadata
routingNumberFieldMetadata

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

ContractorBankAccountFormData​

Shape of the values managed by the contractor bank account form.

Properties​

PropertyType
accountNumberstring
accountType"Checking" | "Savings"
namestring
routingNumberstring

ContractorBankAccountFormField​

ContractorBankAccountFormField = "routingNumber" | "accountNumber" | "name" | "accountType"

Field names accepted by the contractor bank account form.

ContractorBankAccountOptionalFieldsToRequire​

ContractorBankAccountOptionalFieldsToRequire = OptionalFieldsToRequire<typeof requiredFieldsConfig>

Keys of optional contractor bank account fields that can be promoted to required via the hook's optionalFieldsToRequire option.

ContractorBankAccountTypes​

const ContractorBankAccountTypes: readonly ["Checking", "Savings"]

Supported bank account type values: checking and savings.

Endpoints​

MethodPath
GET/v1/contractors/:contractorUuid/bank_accounts
POST/v1/contractors/:contractorUuid/bank_accounts