Track payment status events and report from within your platform

Transaction Event Monitoring

Integrated platforms may choose to have their software application track and automatically update the status of each payment transaction issued through the ACHQ Payment Gateway. In order to accomplish this, you will want to perform Payment Event Tracking queries through the ACHQ Event Monitoring API.

The purpose of this document is not only to explain how to perform this query, but it also presents the concepts necessary for understanding what data will be returned, when status tracking queries should take place, and what the query response data should mean to your software application. Please read each section carefully

Depending on the option that best fits your software deployment scenario, you may choose to retrieve status results for all your merchants in one query or you can choose to query the status results from one specific merchant only.

Conceptual Overview of ACH Clearing

Unlike credit cards, ACH transaction are not instantly verified and approved. This is due to the rules that govern the United States Federal Reserve and the fragmented structure of the current banking system. The banking industry is working now to make all forms of bank transfer and authorization occur in real-time, but due to political, economic, and consumer protection issues, that technology is still a few years out. FedNow - coming soon™ to ACHQ

What has been implemented instead is a system that still provides authorization, but over a period of days instead of seconds. There are several reasons for the slowness of the process, but the bottom line is that the process has been made logistically slow on purpose to protect bank account owners from fraud and error.

Instead of being sent between banks in real-time, all electronic check transactions are batched and sent between banks intraday and overnight through the Federal Reserve (on banking business days only). A bank has up to 48 hours post effective date to respond to an ACH Entry with a Return. If no response is received within that timeframe, the transaction is considered approved (Cleared) and the merchant is paid.

Please note that although banks are expected to respond within the 48 hour timeframe for "standard returns," there are some exceptions to this rule because of laws that protect the customer. If a Return is received after an ACH payment has been Cleared and funds have been settled to the merchant’s account, the Return transaction is classified as a Charged Back because funds will need to be “charged back” from the merchant’s account and returned to the customer’s bank.

As absurd as this process seems in an age of global networks and real-time information exchange, ACH payment processing was designed as an extension to the proven paper check process that the banking industry has used for over 100 years.

Credit card transactions can be approved instantly because they are simply loans that can be paid back or disputed over time. Check transactions, however, provide direct access to a customer’s money and are therefore currently subject to a slower and more careful authorization process.

Events and How They Affect Transaction Status

When tracking and reporting the status an ACH transaction, it is important to understand that events progressively determine the Current Status of a transaction. This means, for example, that when a transaction is submitted for authorization or when a bank indicates that a transaction has been rejected, the current status of the transaction will change because of this event.

The following chart shows every possible event that can affect the current status of a transaction using the actual syntax returned by the ACHQ API as the Event name and the new Current Status of the transaction:

EventACHQ StatusDescriptionPossible Actions
CreatedScheduledPayment is pending delivery to the FedCancel a payment , Update a payment , Hold a payment
CancelledCancelledPayment has been cancelled prior to originationNone
Failed VerificationRejectedBank account failed verification (pre-processing)None (contact customer)
SubmittedIn-processPayment has been sent to FedNone
Returned-NSFReturned-NSFPayment failed due to the receiver not having enough funds to cover the debitCreate a payment
Returned-OtherReturned-OtherPayment failed due to administrative reasons (account closed, frozen, etc)None (contact customer)
ClearedClearedMerchant or Receiver has been paidRefund a payment
Charged BackCharged BackACH return received after settlement deposit was madeNone (contact customer)
Held by MerchantMerchant HoldMerchant or Platform has placed a hold on paymentCancel a payment , Update a payment , Hold a payment
Held by ProcessorProcessor HoldACHQ has placed a hold on the payment pending further review.Cancel a payment
Hold ReleasedHold ReleasedA timestamped, temporary "status" that indicates when a hold status was removed.None


For a more detailed look at ACH return codes, check out the return codes guide

Implementation Guide

Integrating a transaction event monitoring using the ACHQ API into your current application is not difficult. The following is an overview of the major components of this task:

Submitting an API request

The Payment Event Tracking section has all the details on the call parameters, but we will address them in more detail shortly.

Event Processing

The ACHQ API will return a comma delimited text response after it receives and processes the status tracking query request. The fields included in the test response are listed in the next section of this document titled Event Tracking Response Codes


Need to know basis

Please note that a status tracking querying does not provide the status for all transactions, but instead, it returns only those transactions whose status has been changed by an event that occurred on the Tracking Date specified in the query.

This may seem counterintuitive but it allows your platform to only worry about new events while not having to check the status of individual payments ad infinitum

The Event Schedule

The ACHQ system receives transaction status updates throughout the day. Returns can be processed all the way up until midnight (12:00 AM) Central Standard Time. We recommend the following query times (all times EST)

  • 9 AM
  • 1 PM ET
  • 7 PM ET
  • 12 AM ET

Most platforms will want to query API at a minimum of every night after 12:00 AM CST in order to ensure they are updating their database with all status changes that occurred the previous day.

Auditing and Error Handling

There may be times when a tracking update does not occur properly. Reasons for this might include an execution failure of your application, a communication problem over the Internet, and even a problem on the ACHQ platform. As always, it would be wise to incorporate some form of auditing and error handling into your system that knows when your tracking query executed successfully and when it did not. Not only will this help you know when a problem has occurred, but it can also be useful if you want to automate the process of re-scheduling and retrying status tracking queries that failed due to a communication error.