Contractor payment group submission blockers and unblock options

Contractor payment group submission blockers are risk controls that prevent immediate processing of contractor payments under certain conditions. These blockers help mitigate financial risks associated with faster ACH processing for contractor payments.

There are two main types of submission blockers for contractor payment groups:

Earned Fast ACH - Requires partners to demonstrate successful payment history before accessing faster ACH processing
Fast ACH Threshold Exceeded - Triggers when payment amounts exceed predetermined risk thresholds

📘
Minimum API version
Use of Contractor Payment Groups submission blockers requires a minimum API version of v2025-06-15. For additional information on upgrading your version, consult our Version upgrade guide.

Submission blockers

Earned Fast ACH

This blocker applies when a partner is newly onboarded, or hasn't yet earned access to fast ACH processing for payrolls and contractor payments, as they haven’t processed the required number of payrolls over the specified time period.

Only applicable to direct deposit payments (check payments are not affected), blocking all direct deposit payments regardless of the amount.
Returns in submission_blockers array during preview and creation

How to enable:

Please contact your Partner Growth Manager and Technical Solutions representatives to enable this feature for you.

Fast ACH threshold

This blocker triggers when the total direct deposit amount—the combined total of all pending payments, across payrolls and contractor payment groups—exceeds the partner's configured fast_ach_threshold.

How to enable:

Please contact your Partner Growth Manager and Technical Solutions representatives to enable this feature for you.

How to unblock

1. Preview contractor payment group

Call preview a contractor payment group to identify potential submission blockers before creating the contractor payment group:

curl --request POST \
     --url https://api.gusto-demo.com/v1/companies/company_id/contractor_payment_groups/preview \
     --header 'X-Gusto-API-Version: 2025-06-15' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'

Example response with submission blockers:

{
  "submission_blockers": [
    {
      "blocker_type": "needs_earned_access_for_fast_ach",
      "blocker_name": "Needs Earned Access For Fast ACH",
      "selected_option": null,
      "status": "unresolved",
      "unblock_options": [
        {
          "unblock_type": "wire_in",
          "check_date": "2025-07-29",
          "metadata": {
            "wire_in_deadline": "2025-07-29T18:00:00Z",
            "wire_in_amount": "475.0"
          }
        },
        {
          "unblock_type": "move_to_four_day",
          "check_date": "2025-07-29",
          "metadata": {
            "debit_date": "2025-07-23"
          }
        }
      ]
    }
  ]
}

2. Select an unblock option

When submission blockers are present, partners have two options to proceed with contractor payment processing:

Wire transfer: Allows immediate processing by funding the payment via wire transfer.
Move to four-day payroll processing speed

Wire transfer unblock

Include the unblock option in your request to create a contractor payment group), e.g. a wire_in unblock option:

curl --request POST \
     --url https://api.gusto-demo.com/v1/companies/company_id/contractor_payment_groups \
     --header 'X-Gusto-API-Version: 2025-06-15' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "check_date": "2024-05-07",
  "creation_token": "45ef81bb-ae24-4ad1-b2c6-6e563a4c30ed",
  "contractor_payments": [...],
  "submission_blockers": [
    {
      "blocker_type": "{{blocker_type}}",
      "selected_option": "wire_in",
      "selected_option": null,
      "status": "unresolved",
      "unblock_options": [
        {
          "unblock_type": "wire_in",
          "check_date": "2025-07-29",
          "metadata": {
          "wire_in_deadline": "2025-07-29T18:00:00Z",
          "wire_in_amount": "475.0"
          }
        }
      ]
    }
  ]
}
'

Receive credit_blockers array in the response with wire transfer details
Submit the wire transfer using the provided wire_in_request_uuid and wire_in_amount

curl --request PUT \
     --url https://api.gusto-demo.com/v1/wire_in_requests/c5fdae57-5483-4529-9aae-f0edceed92d4 \
     --header 'X-Gusto-API-Version: 2025-06-15' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "amount_sent": "1014500.00",
  "bank_name": "JP Morgan Chase",
  "date_sent": "2024-06-10"
}
'

Payment processes immediately upon wire transfer confirmation

Four-day processing

The other option for unblocking submission blockers for contractor payment groups is to process the payment using standard four-day ACH timing instead of fast ACH.

Process Flow:

Create contractor payment group with move_to_four_day unblock option
Payment is scheduled for standard four-day ACH processing
No additional funding required from partner

{
  "selected_option": "move_to_four_day",
  "submission_unblock": {
    "blocker_type": "fast_ach_threshold_exceeded",
    "selected_option": "move_to_four_day"
  }
}

Payment method considerations

Direct deposit payments

Subject to both Earned Fast ACH and Fast ACH Threshold blockers
Require unblock option selection when blockers are present
Contribute to threshold calculations

Check payments

Not subject to submission blockers
Process normally regardless of blocker status
Do not contribute to threshold calculations
Do not require unblock options

Mixed payment methods

When a contractor payment group contains both direct deposit and check payments:

Submission blockers apply based on the direct deposit portion
Check payments within the group are not affected by blockers
Total amounts for threshold calculations only include direct deposit amounts

Error handling

Common error scenarios

Missing unblock option:

{
  "errors": [
    {
      "error_key": "request",
      "category": "validation_error",
      "message": "Submission unblock option is required when blockers are present"
    }
  ]
}

Invalid creation token:

{
  "errors": [
    {
      "error_key": "request", 
      "category": "validation_error",
      "message": "The preview/calculate step must first be run for this payment before submission"
    }
  ]
}

Wire transfer already submitted:

{
  "errors": [
    {
      "error_key": "wire_in_request",
      "category": "invalid_operation", 
      "message": "Wire in request status must be awaiting funds"
    }
  ]
}

Best practices

Always preview first: Use the preview endpoint to identify blockers before creating contractor payment groups
Handle mixed payments: Account for different behaviors between direct deposit and check payments
Monitor thresholds: Consider cumulative payment amounts across all inflight payments
Validate tokens: Ensure the same creation tokens from preview are used in create requests
Error recovery: Implement proper error handling for common blocker scenarios

Testing considerations

Test scenarios

Earned Fast ACH testing:

Verify blockers appear for new partners without earned access
Confirm check-only payments bypass blockers
Test both unblock options (wire transfer and four-day processing)

Fast ACH Threshold testing:

Test payments above and below configured thresholds
Verify cumulative threshold calculations with multiple inflight payments
Test mixed payment methods within single contractor payment groups

Edge cases:

Payments exactly equal to threshold amounts
Cancellation scenarios with pending wire transfers
Multiple contractor payment groups approaching threshold limits

Configuration testing

Verify proper partner and company configuration before testing:

Confirm required partner settings are enabled
Validate company assignment to appropriate demo scenarios
Test both blocker types independently and in combination

Troubleshooting

Blockers not appearing:

Verify partner has contractor_payment_submit_blockers_enabled
Check that payment methods include direct deposits
Confirm company meets criteria for blocker activation

Unblock options not working:

Validate creation token from preview step
Ensure proper JSON formatting for unblock options
Check that wire transfer capabilities are enabled for partner

Threshold calculations:

Remember thresholds consider all inflight payments
Verify threshold amounts include only direct deposit portions
Check for existing payrolls that contribute to threshold totals