ACH Return Generator File Layout (Version 2)
v2 - USE AFTER 3/2/2024 ONLY
IMPORTANT: Version 1 of the Return Generator file should continue to be utilized until Version 2 is moved to production. Please see additional information below.
On January 31st, 2024, Evolve released v3.3 of the ACH Trace file and v2 of the ACH Return Generator file on the Evolve Enterprise Plus documentation site. This release included breaking changes to both files.
We have offered a 30 day window to adhere to the file layouts. On Saturday, March 2nd, 2024, Evolve will deprecate previous versions of Trace and Return Generator files (including Return Generator v1).
If continuing to use the Return Generator file through 3/2/2024, please utilize the version 1 layout outlined here: ACH Return Generator File Layout (Version 1)
Overview
Platforms can submit the Return Generator file to Evolve to return a received ACH transaction. Once submitted, Evolve will generate a NACHA formatted ACH return file on behalf of the Platform and send the return to the Federal Reserve ACH Network.
The Platform should use the data from the vAccount ACH Receiving File and a valid return reason to submit this file. This file needs to be submitted to Evolve within 24 hours of the Platform receiving the ACH being returned. Evolve will email the Platform the details of any submitted records that could not be used to generate an ACH return file.
File Name
ReturnGen_v2_yyyyMMddHHmmss.achreturns
- ReturnGen indicates the file type
- v2 indicates the version
- yyyyMMddHHmmss is the date/time stamp for when the file was sent
File Direction
This file is sent to Evolve from the Platform.
Format Options
This file type is sent to Evolve in JSON format.
Delivery Window
This file can be delivered to Evolve at any time throughout the week (Monday-Sunday). However, this file needs to be submitted to Evolve within 24 hours of the Platform receiving the ACH being returned. Evolve processes and generates ACH returns upon receipt of this file.
Example:
If a client receives an incoming ACH on Monday that they wish to return, they will need to submit a Return Gen file containing that record by Tuesday at 8pm CST to ensure that the other Financial Institution honors the return.
File Size
This file should contain no more than 2,500 records. If there are more than 2,500 records, the Platform should submit multiple files.
File Options
ACH Return Generator JSON Sample Data
{
"returns": [
{
"ODFI_trace": "242071758896195",
"effective_date": "2020-05-12",
"ach_company_name": "COMENITY PAY OT",
"amount": 105,
"return_reason": "R01",
"client_trace": "123456789999999",
"CoreFileKey": "1305630172514803196946222",
"CoreBatch": 12.0,
"CoreSeq": 1.0
},
{
"ODFI_trace": "021000025622593",
"effective_date": "2020-05-12",
"ach_company_name": "CITY PUBLIC SRV",
"amount": 364.61,
"return_reason": "R01",
"client_trace": "123456789999999",
"CoreFileKey": "1305630172514803196946222",
"CoreBatch": 12.0,
"CoreSeq": 2.0
},
{
"ODFI_trace": "061036010000339",
"effective_date": "2020-05-12",
"ach_company_name": "IRS",
"amount": 5,
"return_reason": "R03",
"CoreFileKey": "8141411394634194906376641",
"CoreBatch": 56.0,
"CoreSeq": 1.0
},
{
"ODFI_trace": "021214899147540",
"effective_date": "2020-05-11",
"ach_company_name": "tapx_trading_and",
"amount": 0.56,
"return_reason": "R01",
"client_trace": "123456789999999",
"CoreFileKey": "9379203039964376985965724",
"CoreBatch": 78.0,
"CoreSeq": 1.0
}
]
}
ACH Return Generator File Table
Field Name | Data Type | Data Validation | Description |
---|---|---|---|
ODFI_trace | string | required | 15 character trace number provided by the Originating Bank (ODFI) sending the transaction. Insert leading zeros if necessary. See "ODFI_trace" in vAccount ACH Receiving v3.5 file. |
effective_date | string | required | The effective date of the received ACH transaction from the ODFI (yyyy-MM-dd). See "EffectiveDate" in vAccount ACH Receiving v3.5 file. |
ach_company_name | string | required | The name of the company that originated the received ACH. See "PostingData" in vAccount ACH Receiving v3.5 file. |
amount | decimal | required | The unsigned amount of the received ACH. See "Amount" in the vAccount ACH Receiving v3.5 file. |
return_reason | string | required | Represent the reason for returning the received ACH with a NACHA return code. See NACHA Return Codes & Change Codes table. |
client_trace | string | required | Client-supplied 15 character trace number to identify ACH transaction being returned. This trace will serve as client's identification of the return record until a production trace is provided to confirm Fed upload. Recommended Trace Structure: Characters 1-8: First 8 digits of routing number for entity originating return. Characters 9-15: Sequence Number (in ascending order) assigned to each entry within a batch. (Ex. 0000001 for 1st entry, 0000002 for 2nd, etc.) Recommended Best Practice: It is recommended that clients assign a running sequence number to client_trace sequence values rather than restarting at 0000001 each file. |
CoreFileKey | string | optional | Evolve Core-system generated File Key identifier associated with the previously received ACH transaction to be returned. CoreFileKey can be found in the original vAccount ACH Receiving record from the vAccount ACH Receiving v3.5 file. |
CoreBatch | number | optional | Evolve Core-system generated Batch identifier associated with the previously received ACH transaction to be returned. CoreBatch can be found in the original vAccount ACH Receiving record from the vAccount ACH Receiving v3.5 file. |
CoreSeq | number | optional | Evolve Core-system generated Sequence identifier associated with the previously received ACH transaction to be returned. CoreSeq can be found in the original vAccount ACH Receiving record from the vAccount ACH Receiving v3.5 file. |
NACHA Return Codes & Change Codes
Field Name | Description |
---|---|
C01 | Incorrect bank account number |
C02 | Incorrect routing number |
C03 | Incorrect routing and account number |
C05 | Incorrect Payment Code |
R01 | Insufficient Funds |
R02 | Account Closed |
R03 | No Account/Unable to Locate Account |
R04 | Invalid Account Number |
R06 | Returned per ODFI’s Request |
R07 | Authorization Revoked by Customer |
R08 | Stop Payment on Item |
R09 | Uncollected Funds |
R10 | Customer Advises Not Authorized |
R11 | Check Truncation Entry Return |
R12 | Branch Sold to Another DFI |
R13 | RDFI not qualified to participate |
R14 | Representative Payee Deceased |
R15 | Beneficiary or Account Holder Deceased |
R16 | Account Frozen |
R17 | File Record Edit Criteria |
R20 | Non-Transaction Account |
R21 | Invalid Company Identification |
R22 | Invalid Individual ID Number |
R23 | Credit Entry Refused by Receiver |
R24 | Duplicate Entry |
R28 | Check digit for routing number is incorrect |
R29 | Corporate Customer Advises Not Authorized |
R31 | Permissible Return Entry |
R33 | Return of XCK Entry |
R34 | Limited Participation D.F.I. |
R35 | Return of Improper Debit Entry |
R36 | Return of Improper Credit Entry |
R37 | Source Document Presented for Payment |
R38 | Stop Payment on Source Document |
R39 | Improper Source Document |
R40 | Non Participant in E.N.R. Program |
R41 | Invalid Transaction Code (E.N.R. only) |
R42 | Routing Number/Check Digit Error |
R43 | Invalid D.F.I. Account Number |
R44 | Invalid Individual I.D. Number |
R45 | Invalid Individual Name |
R46 | Invalid Representative Payee Indicator |
R47 | Duplicate Enrollment |
R50 | State Law Prohibits Truncated Checks |
R51 | NULL |
R52 | Stop Pay on Item |
R53 | Item and ACH Entry Presented for Payment |
R61 | Misrouted Return |
R67 | Duplicate Return |
R68 | Untimely Return |
R69 | Field Errors |
R70 | Permissible Return Entry Not Accepted |
R71 | Misrouted Dishonor Return |
R72 | Untimely Dishonored Return |
R73 | Timely Original Return |
R74 | Corrected Return |
R75 | Original Return not a Duplicate |
R76 | No Errors Found |
R80 | Cross-Border Payment Coding Error |
R81 | Non-Participant in Cross-Border Program |
R82 | Invalid Foreign Receiving D.F.I. Identification |
R83 | Foreign Receiving D.F.I. Unable to Settle |
R84 | Entry Not Processed by O.G.O. |
Release Notes
Release v2 - 2024.02
- Added "v2 - 2024.02" to "Description" subtext field at top of page.
- Syntax updates to Purpose section.
- Syntax update to Format Options section.
- Syntax and punctuation updates to Delivery Window section and "Example,"
- Updated File Options section with new JSON sample data to reflect new fields and existing field name changes.
- Changed Trace field to ODFI_trace.
- Added NACHA Return Codes & Change Codes link to return_reason field description.
- Added new fields and related descriptions for each:
- client_trace
- CoreFileKey
- CoreBatch
- CoreSeq
- Added "Release Notes" section.
Updated 8 months ago