Testing Payments in Sandbox

In Sandbox, you have two options for testing payments flows:

• Automatic Simulation
• Manual Simulation

To switch between these two modes, set the simulation_mode property on the Payroll object (only available in Sandbox) to automatic or manual.

Automatic Simulation (default)

By default, payrolls in Sandbox will automatically transition to the next phase of payroll processing (i.e., from pending to processing, and from processing to paid) every 5 minutes. To start the process, you just need to create and approve a payroll.

To test failed payments, use manual simulation.

Manual Simulation

Check additionally offers the ability to manually simulate payments processing with a set of endpoints on the Payroll API. These endpoints allow you to manually trigger the completion or failure of the payroll debit, and the completion of employee direct deposit disbursements.

To use these endpoints, first update the simulation_mode property on the Payroll to manual.

• ACH-funded payrolls: Use the Start processing endpoint to transition the payroll to a processing status, then call the complete or fail funding endpoints from there.
• Wire-funded payrolls: Skip the start processing step. Wire payrolls remain in pending status until funding completes, so call the Complete funding endpoint directly from pending. Note that funding failure simulation is not available for wire-funded payrolls, as wire payments do not have ACH returns.

Failed employer debit

To simulate a failed employer debit, call [Sandbox] Fail funding after the payroll reaches processing.

Each simulated funding failure records a funding strike against the company. To reset a company's strikes after testing, use [Sandbox] Remove funding strikes.

Individual payments

You can also settle or fail one payment at a time with [Sandbox] Complete payment and [Sandbox] Fail payment. This lets you test a failed direct deposit for one employee or contractor while the rest of the payroll is paid.

1. Create a payroll with simulation_mode set to manual, then preview and approve it.
2. Call [Sandbox] Start processing, then [Sandbox] Complete funding.
3. Find the payroll's payments with List payments. Each employee and contractor direct deposit is a credit, identified by its parent_type and parent_id.
4. Call [Sandbox] Fail payment on the credit you want to fail, and [Sandbox] Complete payment on the others. The failed payment moves to failed and the payroll moves to partially_paid.
5. To test recovery, add a new bank account for that employee or contractor and call Retry a payment with it. A failed credit can only be retried to a new bank account. See Handling Failed Payments.

Both endpoints require the payment to have a status of processing. Right after Start processing, a payroll's payments are draft for a few seconds, so wait until they're processing.