Payment event tracking
Overview
As previously mentioned [way too many times] ACH payments operate on an asynchronous batch-> return cycle. To help simplify event tracking for ACH payments we have developed an easy to use query system that only provides updates on payments with status (event) updates.
Due to the long-tail potential for ACH returns being up to 60 days for ACH disputes, it would create enormous technical debt if your system were required to monitor each payment for updates multiple times per day for months on end.
Fields and Values
The following values are specific to creating an event query:
| Field Name | Usage | Description |
|---|---|---|
| ProviderID | Required | Provided to you by your Relationship Manager |
| Provider_GateID | Required | Provided to you by your Relationship Manager |
| Provider_GateKey | Required | Provided to you by your Relationship Manager |
| CommandVersion | Required | Set to 2.0 for this API version |
| Command | Required | Set to ECheckReports.StatusTrackingQuery |
| TrackingDate | Required | The date for which you want to retrieve status update information. Accepted formats (MM/DD/YYYY or MMDDYYYY) |
| MerchantID | Optional | A value for this field is only necessary if you intend to limit the results to a single ACHQ merchant |
That's all pretty familiar, right? Here's what it looks like with a code sample:
curl --request POST \
--url 'https://www.speedchex.com/datalinks/transact.aspx/?ProviderID=99&Provider_GateID=test&Provider_GateKey=test&CommandVersion=2.0&Command=ECheckReports.StatusTrackingQuery' \
--header 'Accept: application/json' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data TrackingDate=06172022
Response Format
The response format is slightly different than the JSON payloads that we're used to. An update to this format is in the late stages of development as of February 2023. Webhooks with dynamic templates are up next - hang tight!
For now, the API returns the following values after a successful query:
| Return Field | Value Format Constraints | Max Length |
|---|---|---|
| Transact_ReferenceID | The unique ID returned when this payment was originally submitted. Our favorite value. | 50 |
| Provider_TransactionID | The unique ID your software assigned to this payment when the payment transaction was originally submitted | 50 |
| MerchantID | The ACHQ MerchantID assigned to this payment when it was submitted | - |
| Event Name | The event that occurred to this payment on the specified Tracking Date. The possible values are defined in the chart titled Transaction Events and Resulting Status Values earlier in this document. | 20 |
| Event Date/Time | The date & time (CST) when this event occurred. Format: MM/DD/YYYY HH:MM:SS (24-hour military time) | 19 |
| Resulting Status | The status of this payment resulting from the event that occurred. The possible values are defined in the chart titled Transaction Events and Resulting Status Values earlier in this document. | 20 |
| Return Code | A 3 letter code assigned to the transaction only if the Resulting Status value is ‘Returned’ or ‘Charged Back’. | 3 |
| Return Explanation | The explanation for the return. Please refer to Return Codes for a list of all possible return codes and their explanations. | 255 |
| Verification Status | Returns one of following responses: POS – Account found in good standing NEG – Account is invalid or has negative status UNK – Bank not participating / Account status unknown ERR – Account could not be verified due to system error . | 3 |
| Verification Code | Please see Bank Account Response Codes for all possible values for this field. | 3 |
| Verification Description | Please see Bank Account Response Codes for all possible values for this field. | 100 |
No Verify, No Result
If a payment is not validated via the ACH bank account insight endpoint or via merchant insight settings, there will be no value returned for the Verification Status, Verification Code, or Verification Description fields. Seems obvious but you never know.
Sample Response
14447204,payment_transaction#228,2001,Created,06/17/2022 05:00:59,Scheduled,,,,,
14449325,payment_transaction#235,2001,Created,06/17/2022 08:13:03,Scheduled,,,,,
14450935,12345,2001,Created,06/17/2022 14:35:07,Scheduled,,,,,
14451050,,2001,Created,06/17/2022 14:35:07,Scheduled,,,,,
14451052,,2001,Created,06/17/2022 14:35:07,Scheduled,,,,,
14451053,,2001,Created,06/17/2022 14:35:07,Scheduled,,,,,
14451081,,2001,Created,06/17/2022 14:35:07,Scheduled,,,,,
14451096,,2001,Created,06/17/2022 14:35:07,Scheduled,,,,,
14451114,,2001,Created,06/17/2022 14:35:07,Scheduled,,,,,
14451922,,2001,Created,06/17/2022 14:35:07,Scheduled,,,,,
14452064,,2001,Created,06/17/2022 14:35:07,Scheduled,,,,,
14450988,12345,2001,Created,06/17/2022 14:45:10,Scheduled,,,,,
14451106,12345,2001,Created,06/17/2022 15:13:06,Scheduled,,,,,
14450935,12345,2001,Cancelled,06/17/2022 15:14:29,Cancelled,,,,,
14451050,,2001,Cancelled,06/17/2022 15:14:29,Cancelled,,,,,
14451052,,2001,Cancelled,06/17/2022 15:14:29,Cancelled,,,,,
14451053,,2001,Cancelled,06/17/2022 15:14:29,Cancelled,,,,,
14451081,,2001,Cancelled,06/17/2022 15:14:29,Cancelled,,,,,
14451096,,2001,Cancelled,06/17/2022 15:14:29,Cancelled,,,,,
14451114,,2001,Cancelled,06/17/2022 15:14:29,Cancelled,,,,,
14451922,,2001,Cancelled,06/17/2022 15:14:29,Cancelled,,,,,
14452064,,2001,Cancelled,06/17/2022 15:14:29,Cancelled,,,,,
14451115,12345,2001,Created,06/17/2022 15:17:05,Scheduled,,,,,
14451125,12345,2001,Created,06/17/2022 15:17:19,Scheduled,,,,,
14451129,,2001,Created,06/17/2022 15:17:19,Scheduled,,,,,
14451125,12345,2001,Authorization,06/17/2022 15:17:52,Authorized,,,,,
14451129,,2001,Authorization,06/17/2022 15:17:52,Authorized,,,,,
14447204,payment_transaction#228,2001,Submitted,06/17/2022 16:00:23,In-Process,,,,,
14449325,payment_transaction#235,2001,Submitted,06/17/2022 16:00:23,In-Process,,,,,
14450988,12345,2001,Submitted,06/17/2022 16:00:23,In-Process,,,,,
14451106,12345,2001,Submitted,06/17/2022 16:00:23,In-Process,,,,,
14451115,12345,2001,Submitted,06/17/2022 16:00:23,In-Process,,,,,
14451886,12345,2001,Created,06/17/2022 19:40:10,Scheduled,,,,,
14451890,12345,2001,Created,06/17/2022 19:42:11,Scheduled,,,,,
14451893,12345,2001,Created,06/17/2022 19:42:11,Scheduled,,,,,
14451895,12345,2001,Created,06/17/2022 19:42:12,Scheduled,,,,,
14451901,21321312,2001,Created,06/17/2022 19:46:11,Scheduled,,,,,
14451918,21321312,2001,Created,06/17/2022 19:54:10,Scheduled,,,,,
14451923,12345,2001,Created,06/17/2022 19:58:10,Scheduled,,,,,
14451929,12345,2001,Created,06/17/2022 19:58:12,Scheduled,,,,,
14451932,,2001,Created,06/17/2022 19:58:12,Scheduled,,,,,
14451933,,2001,Created,06/17/2022 19:58:12,Scheduled,,,,,
14451934,,2001,Created,06/17/2022 19:58:12,Scheduled,,,,,
14451946,,2001,Created,06/17/2022 19:58:12,Scheduled,,,,,
14451947,,2001,Created,06/17/2022 19:58:12,Scheduled,,,,,
14451949,,2001,Created,06/17/2022 19:58:12,Scheduled,,,,,
14451950,,2001,Created,06/17/2022 19:58:12,Scheduled,,,,,
14451953,,2001,Created,06/17/2022 19:58:12,Scheduled,,,,,
14452065,,2001,Created,06/17/2022 19:58:12,Scheduled,,,,,
14452068,,2001,Created,06/17/2022 19:58:12,Scheduled,,,,,
14452015,21321312,2001,Created,06/17/2022 20:16:10,Scheduled,,,,,
14452021,21321312,2001,Created,06/17/2022 20:20:11,Scheduled,,,,,
14452028,21321312,2001,Created,06/17/2022 20:20:13,Scheduled,,,,,
14452034,21321312,2001,Created,06/17/2022 20:24:10,Scheduled,,,,,
14452036,21321312,2001,Created,06/17/2022 20:24:11,Scheduled,,,,,
14452041,21321312,2001,Created,06/17/2022 20:26:12,Scheduled,,,,,
14452044,21321312,2001,Created,06/17/2022 20:26:13,Scheduled,,,,,
14452069,12345,2001,Created,06/17/2022 20:36:11,Scheduled,,,,,
14452073,,2001,Created,06/17/2022 20:36:11,Scheduled,,,,,
14452075,,2001,Created,06/17/2022 20:36:11,Scheduled,,,,,
14452077,12345,2001,Created,06/17/2022 20:38:11,Scheduled,,,,,
14452084,,2001,Created,06/17/2022 20:40:12,Scheduled,,,,,
14452087,12345,2001,Created,06/17/2022 20:42:10,Scheduled,,,,,
14452101,,2001,Created,06/17/2022 20:42:10,Scheduled,,,,,
14452094,,2001,Created,06/17/2022 20:44:12,Scheduled,,,,,
14452096,,2001,Created,06/17/2022 20:46:10,Scheduled,,,,,
14452098,,2001,Created,06/17/2022 20:46:11,Scheduled,,,,,
14452087,12345,2001,Cancelled,06/17/2022 20:47:27,Cancelled,,,,,
14452101,,2001,Cancelled,06/17/2022 20:47:27,Cancelled,,,,,
14452111,12345,2001,Created,06/17/2022 20:50:11,Scheduled,,,,,
14452114,12345,2001,Created,06/17/2022 20:50:12,Scheduled,,,,,
14452115,12345,2001,Created,06/17/2022 20:50:13,Scheduled,,,,,
14452119,12345,2001,Created,06/17/2022 20:52:10,Scheduled,,,,,
14452126,,2001,Created,06/17/2022 20:52:10,Scheduled,,,,,
14452119,12345,2001,Cancelled,06/17/2022 20:52:26,Cancelled,,,,,
14452126,,2001,Cancelled,06/17/2022 20:52:26,Cancelled,,,,,
14452127,12345,2001,Created,06/17/2022 20:54:10,Scheduled,,,,,
14452129,12345,2001,Created,06/17/2022 20:54:11,Scheduled,,,,,
14452139,,2001,Created,06/17/2022 20:54:11,Scheduled,,,,,
14452129,12345,2001,Cancelled,06/17/2022 20:55:40,Cancelled,,,,,
14452139,,2001,Cancelled,06/17/2022 20:55:40,Cancelled,,,,,
14452140,12345,2001,Created,06/17/2022 20:56:18,Scheduled,,,,,
14452345,21321312,2001,Created,06/17/2022 22:12:12,Scheduled,,,,,
14452348,21321312,2001,Created,06/17/2022 22:18:12,Scheduled,,,,,
14452389,21321312,2001,Created,06/17/2022 22:40:13,Scheduled,,,,,
14452402,21321312,2001,Created,06/17/2022 22:50:12,Scheduled,,,,,
14452403,21321312,2001,Created,06/17/2022 22:50:13,Scheduled,,,,,
14452404,21321312,2001,Created,06/17/2022 22:50:13,Scheduled,,,,,
14452405,21321312,2001,Created,06/17/2022 22:52:12,Scheduled,,,,,
Updated almost 2 years ago