Contractor payment group submission blockers

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:

1. Earned Fast ACH - Requires partners to demonstrate successful payment history before accessing faster ACH processing
2. 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:

bash

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:

bash

{
  "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:

bash

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

bash

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:

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

bash

{
  "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:

bash

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

Invalid creation token:

bash

{
  "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:

bash

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

Best practices

1. Always preview first: Use the preview endpoint to identify blockers before creating contractor payment groups
2. Handle mixed payments: Account for different behaviors between direct deposit and check payments
3. Monitor thresholds: Consider cumulative payment amounts across all inflight payments
4. Validate tokens: Ensure the same creation tokens from preview are used in create requests
5. 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

---

Contractor Payment Receipts

Manage contractor forms and documents