Resolve Funding Failures

An employer that fails to fund payroll will be blocked from running additional payrolls until all its funding failures are resolved. When a payroll debit fails, a funding failure requirement is created in Check's system to track the funding recovery process. An employer with outstanding funding failure requirements will be unable to run payroll until these funds are recovered.

The Requirements API provides the ability to identify these individual blockers on running payroll and track updates to the status of the funding recovery process for a given company, such as when an ACH redebit attempt is issued, the debit is retried via wire, or the funds have been successfully recovered.

curl -X GET \
  https://sandbox.checkhq.com/requirements?requirement=resolve_funding_failure \
  -H 'Authorization: Bearer YOUR_API_KEY'

To view all funding failures for a particular company, you can optionally pass in the company ID as a query parameter to the endpoint. Until these all of requirements are resolved, the company will be unable to run additional payrolls.

curl -X GET \
  https://sandbox.checkhq.com/requirements?company=com_yvgimu7i60cwfod0jhaft&requirement=resolve_funding_failure \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
    "next": null,
    "previous": null,
    "results": [
        {
            "id": "req_hftmhftmhftmhftmhftm",
            "company": "com_yvgimu7i60cwfod0jhaft",
            "employee": null,
            "responsible_entity": "company",
            "requirement": "resolve_funding_failure",
            "categories": [
                "failed_payroll_debit"
            ],
            "status": "open",
            "errors": [],
            "guidance": {
                "document_options": null,
                "funding_detail": {
                    "payment": "pyt_2UjTShT7NqrfwLXF2WSG",
                    "payroll": "pay_vfywjO2tf6XnvVlDWHzw",
                    "funding_status": "ach_redebit_inflight",
                    "funding_message": "An ACH redebit attempt has been issued for this employer."
                }
            }
        },
        {
            "id": "req_rtxmhftmhftmhftmhftx",
            "company": "com_yvgimu7i60cwfod0jhaft",
            "employee": null,
            "responsible_entity": "company",
            "requirement": "resolve_funding_failure",
            "categories": [
                "failed_payroll_debit"
            ],
            "status": "open",
            "errors": [],
            "guidance": {
                "document_options": null,
                "funding_detail": {
                    "payment": "pyt_9ZjTShT7NqrfwLXF2WSF",
                    "payroll": "pay_XmLwjO2tf6XnvVlDWHzw",
                    "funding_status": "expecting_wire",
                    "funding_message": "Check is waiting for the failed debit attempt to be retried via wire."
                }
            }
        }
    ]
}

Example flow for a funding failure recovery via ACH

Step 1: Employer fails to fund payroll

A failed funding Requirement will be issued any time an employer fails to fund payroll. This can also be proactively retrieved by calling the List requirements endpoint.

The funding detail object contains the ID of the failed debit payment, as well as the associated payroll ID. These items can be queried via Check's Payments and Payrolls API to obtain more detailed information. This object also provides information about the funding state. In this case, it is clear that the employer has failed to fund payroll.

{
   "id":"req_hftmhftmhftmhftmhftm",
   "company":"com_yvgimu7i60cwfod0jhaft",
   "employee":null,
   "responsible_entity":"company",
   "requirement":"resolve_funding_failure",
   "categories":[
      "failed_payroll_debit"
   ],
   "status":"failed",
   "errors":[],
   "guidance":{
      "document_options":null,
      "funding_detail":{
         "payment":"pyt_2UjTShT7NqrfwLXF2WSG",
         "payroll":"pay_vfywjO2tf6XnvVlDWHzw",
         "funding_status":"failed",
         "funding_message":"The employer has failed to fund payroll."
      }
   }
}

Step 2: An ACH debit retry is issued

When a failed payroll debit is retried, the funding failure Requirement will update to an open status, reflecting a re-debit attempt and inform the consumer that an ACH re-debit is in-flight. Notice the change in funding_status and funding_message.

{
   "id":"req_hftmhftmhftmhftmhftm",
   "company":"com_yvgimu7i60cwfod0jhaft",
   "employee":null,
   "responsible_entity":"company",
   "requirement":"resolve_funding_failure",
   "categories":[
      "failed_payroll_debit"
   ],
   "status":"open",
   "errors":[],
   "guidance":{
      "document_options":null,
      "funding_detail":{
         "payment":"pyt_2UjTShT7NqrfwLXF2WSG",
         "payroll":"pay_vfywjO2tf6XnvVlDWHzw",
         "funding_status":"ach_redebit_inflight",
         "funding_message":"An ACH redebit attempt has been issued for this employer."
      }
   }
}

Step 3: The ACH debit retry completes and is awaiting the three-day ACH return window

When the re-debit attempt is sent to the employer's bank, the funding failure Requirement transitions to a pending status and the funding detail object contains relevant information including the date on which the re-debit is expected to clear the ACH return window. Note that ACH payments clear the return window on the third banking day following completion (i.e. completed on Monday, cleared on Wednesday).

{
   "id":"req_hftmhftmhftmhftmhftm",
   "company":"com_yvgimu7i60cwfod0jhaft",
   "employee":null,
   "responsible_entity":"company",
   "requirement":"resolve_funding_failure",
   "categories":[
      "failed_payroll_debit"
   ],
   "status":"pending",
   "errors":[],
   "guidance":{
      "document_options":null,
      "funding_detail":{
         "payment":"pyt_2UjTShT7NqrfwLXF2WSG",
         "payroll":"pay_vfywjO2tf6XnvVlDWHzw",
         "funding_status":"ach_redebit_awaiting_return_window",
         "funding_message":"An ACH redebit attempt has successfully completed for this employer, and is waiting for the three day ACH return window to clear on 2022-10-28."
      }
   }
}

Step 4: The ACH debit retry clears the three-day ACH return window

Finally, when the redebit attempt clears the return window, the funding failure Requirement will transition to a resolved status. At this point, the company may be unblocked from running payrolls if are no other unresolved failed funding requirements and the company is otherwise in good standing with Check.

{
   "id":"req_hftmhftmhftmhftmhftm",
   "company":"com_yvgimu7i60cwfod0jhaft",
   "employee":null,
   "responsible_entity":"company",
   "requirement":"resolve_funding_failure",
   "categories":[
      "failed_payroll_debit"
   ],
   "status":"resolved",
   "errors":[],
   "guidance":{
      "document_options":null,
      "funding_detail":{
         "payment":"pyt_2UjTShT7NqrfwLXF2WSG",
         "payroll":"pay_vfywjO2tf6XnvVlDWHzw",
         "funding_status":"resolved",
         "funding_message":"The payroll has been successfully funded and the funding failure has been resolved."
      }
   }
}

Example flow for a funding failure recovery via wire

Step 1: Employer fails to fund payroll

As in the example above, a funding failure Requirement is issued when an employer fails to fund payroll. This requirement will initially have a failed status and contain funding details about the affected payment and payroll.

{
   "id":"req_hftmhftmhftmhftmhftm",
   "company":"com_yvgimu7i60cwfod0jhaft",
   "employee":null,
   "responsible_entity":"company",
   "requirement":"resolve_funding_failure",
   "categories":[
      "failed_payroll_debit"
   ],
   "status":"failed",
   "errors":[],
   "guidance":{
      "document_options":null,
      "funding_detail":{
         "payment":"pyt_2UjTShT7NqrfwLXF2WSG",
         "payroll":"pay_vfywjO2tf6XnvVlDWHzw",
         "funding_status":"failed",
         "funding_message":"The employer has failed to fund payroll."
      }
   }
}

Step 2: A wire debit retry is issued

When a failed payroll debit is retried via wire, the funding failure Requirement updates to an open status. The funding detail field in the Requirement object reflects the expectation that the employer will initiate a wire transfer to fund the payroll.

{
   "id":"req_hftmhftmhftmhftmhftm",
   "company":"com_yvgimu7i60cwfod0jhaft",
   "employee":null,
   "responsible_entity":"company",
   "requirement":"resolve_funding_failure",
   "categories":[
      "failed_payroll_debit"
   ],
   "status":"open",
   "errors":[],
   "guidance":{
      "document_options":null,
      "funding_detail":{
         "payment":"pyt_2UjTShT7NqrfwLXF2WSG",
         "payroll":"pay_vfywjO2tf6XnvVlDWHzw",
         "funding_status":"expecting_wire",
         "funding_message":"Check is waiting for a wire to clear the failed debit attempt."
      }
   }
}

Step 3: Employer wires the funds

As in the example above, once the employer recovers from the funding failures (in this case, by sending a wire), the funding failure Requirement will transition to a resolved status and the company will be allowed to run other payrolls if are no other unresolved failed funding requirements and the company is otherwise in good standing with Check.

{
   "id":"req_hftmhftmhftmhftmhftm",
   "company":"com_yvgimu7i60cwfod0jhaft",
   "employee":null,
   "responsible_entity":"company",
   "requirement":"resolve_funding_failure",
   "categories":[
      "failed_payroll_debit"
   ],
   "status":"resolved",
   "errors":[],
   "guidance":{
      "document_options":null,
      "funding_detail":{
         "payment":"pyt_2UjTShT7NqrfwLXF2WSG",
         "payroll":"pay_vfywjO2tf6XnvVlDWHzw",
         "funding_status":"resolved",
         "funding_message":"The payroll has been successfully funded and the funding failure has been resolved."
      }
   }
}

Webhooks

Similar to other Requirements objects, created and updated webhooks will be sent to indicate the creation of, or update to a funding failure Requirement.