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:
|Event||ACHQ Status||Description||Possible Actions|
|Created||Scheduled||Payment is pending delivery to the Fed||Cancel a payment , Update a payment , Hold a payment|
|Submitted||In-process||Payment has been sent to Fed||None|
|Cleared||Cleared||Merchant or Receiver has been paid||Refund a payment|
|Failed / NSF||Returned-NSF||Payment failed due to the receiver not having enough funds to cover the debit||Create a payment|
|Failed / admin||Returned-Other||Payment failed due to administrative reasons (account closed, frozen, etc)||None (contact customer)|
|Charged-back||Charged Back||ACH return received after deposit was made||None (contact customer)|
|Bad bank account||Rejected||Bank account failed verification (pre-processing)||None (contact customer)|
For a more detailed look at ACH return codes, check out the return codes 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.
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.
Updated 9 months ago