Payments Overview
Gain visibility into employer payroll debits and refunds, employee credit payments, and employer tax collections & refunds using the Payments API
Check’s Payments API allows you to view payments initiated by Check on behalf of employers.
A Payment object can have one of the following parent types, which also indicates its purpose:
- Payroll: Payment was initiated to fund the cash requirement of the payroll, by debiting the employer’s account.
- Payroll Item: Payment was initiated to disburse earnings net of taxes to employees, by crediting the employee’s bank account
- Contractor Payment: Payment was initiated to disburse earnings to contractors, by crediting the contractor’s bank account
- Collection: Payment was initiated to fund the cash requirement of due tax payments as a result from mid-quarter collections or quarterly variance collections.
- Refund: Payment was initiated to disburse over-collected tax funds from payrolls run during a quarter.
Payment Lifecycle
Each Payment has one or more associated Payment Attempts that have one of the following statues in the payments life cycle:
draft
: Payment is created in draft state after a Payroll is approved, but not yet submitted for processing.- Note: Payments fields & associated objects related to a Payroll, such as the payment amount, direction, and the bank account associated with the payment, are set at the time of Payroll Approval. In order to make any changes to those fields and associated objects, you must re-open and re-approve the payroll.
processing
: Payment has been transmitted to the payment processor.- Payment Attempt sent via
ACH
will remain in this state until the end of the distribution and settlement timeline in the FedACH processing schedule - Payment Attempt sent via
Wire
will remain in this state until Check confirms the receipt of the wire payment
- Payment Attempt sent via
paid
: Payment was successfully processed and funds were transferred to the recipient.- Payment Attempt sent via
ACH
will automatically transition to this status at the end of the settlement timeline in the FedACH processing schedule. This may not be a terminal state, as the ACH Protocol allows for payments to be rejected up to two banking days following the expected settlement date. - This state is terminal for Payment Attempt sent via
Wire
- Payment Attempt sent via
failed
: The Payment could not be processed. Common failures include insufficient funds or incorrect account details. You can recover failed payment attempts using the/retry
or/refund
endpoints.refunded
: Indicative of a payment that has been refunded. Once a payment has been refunded, it cannot be undone.
Visit this section of the Docs for more details on the Payment and Payment Attempt objects.
Payment Webhooks
All payments with the above parent types also have corresponding webhooks as the statuses of their underlying payment attempts change. For more information, please see our webhook event types here.
Querying this API
To help employers understand why a certain bank account transaction occurred, a common use case is to query our /payments
endpoint to return all payments of a certain direction, amount, or date.
For more information, see our List Payments endpoint here.
What is not included in this API?
This API can return all types of employer and employee related payments.
Other money movement transactions that Check enables, such as deposits of tax funds to state agencies and deposits of post-tax deduction payments, such as child support garnishments, are outside of the scope of the Payments API.
Updated 4 months ago