ACH Return Overview

note

The features documented here are in a beta state, and this documentation is considered draft material subject to frequent change.

Using our Platform API, you can securely submit ACH Returns to reduce your ACH return rates and automate your ACH return process.

You can query the status and outcomes of your submitted ACH returns to track progress and access resolution details.

ACH Return Fields

Field	Data Type	Description
account_guid	String	The unique identifier for the account associated with the transaction. Defined by MX.
account_number_last_four	String	The last 4 digits of the account number used for the transaction by the Originating Depository Financial Institution (ODFI).
account_type	String	The type of account used for the transaction by the Originating Depository Financial Institution (ODFI) (for example, CHECKING, SAVINGS).
ach_initiated_at	String	The date and time when the transaction was initiated by the Originating Depository Financial Institution (ODFI) in ISO 8601 format without timestamp.
client_guid	String	The unique identifier for the client associated with the ACH return. Defined by MX.
corrected_account_number	String	The account number correction reported by the RDFI. Populate only if the resolution_code is NOTICE_OF_CHANGE.
corrected_routing_number	String	The routing number correction reported by the RDFI. Populate only if the resolution_code is NOTICE_OF_CHANGE. Must be a valid 9-digit routing number format.
created_at	String	Date and time when the ACH return record was created.
external_customer_guid	String	Your unique identifier as defined by a partner.
guid	String	The unique identifier for the ACH return record.
id	String	Client-defined identifier for this specific return submission. Allows you to track and reference you requests.
institution_guid	String	The MX-defined identifier for the institution associated with the ACH return.
investigation_notes	String	Notes added by Product Support during investigation.
member_guid	String	The unique identifier for the member associated with the transaction. Defined by MX.
processing_errors	String	Error messages encountered during processing.
resolution_code	String	A short, machine-readable code that categorizes the type of resolution or reason for the status. See Resolution Codes for a complete list.
resolution_detail	String	A more detailed, human-readable message providing context and next steps related to the return_status and resolution_code.
resolved_status_at	String	Date and time when the return was marked as resolved.
return_account_number	String	Incorrect account number used in the ACH transaction.
return_code	String	The associated ACH return codes and notice of change codes (for example, R02, R03, R04, R05, R20, NOC). See Return Codes for a complete list.
return_notes	String	Notes that you set to inform MX on internal ACH processing.
return_routing_number	String	Incorrect routing number used in the ACH transaction.
return_status	String	The current processing status of the ACH return. See Return Status for a complete list of statuses.
returned_at	String	The date and time when the return was reported by the Receiving Financial Depository Institution (RDFI) in ISO 8601 format without timestamp.
sec_code	String	The SEC code (Standard Entry Class Code) – a three-letter code describing how a payment was authorized (for example, WEB). See SEC Codes for a complete list.
started_processing_at	String	Date and time when MX started processing the return.
submitted_at	String	Date and time when the record was submitted through the API.
transaction_amount	Number	The amount of the transaction.
transaction_amount_range	Number	The transaction amount range, used for impact assessment.
updated_at	String	Date and time when the ACH return record was last updated.
user_guid	String	MX-defined identifier for the user associated with the event.

SEC Codes

Code	Data Type	Title
SEC_CODE_UNSPECIFIED	String	Used if no other SEC code is set.
PPD	String	Prearranged Payment and Deposit
PPD_PLUS	String	Prearranged Payment and Deposit, with addenda record
CCD	String	Corporate Credit or Debit
CCD_PLUS	String	Corporate Credit or Debit, with addenda record
CTX	String	Corporate Trade Exchange
WEB	String	Internet Initiated/Mobile Entry
TEL	String	Telephone-Initiated Entry
ARC	String	Accounts Receivable Entry
BOC	String	Back Office Conversion Entry
POP	String	Point-of-Purchase Entry
IAT	String	International ACH Transaction
COR	String	Notification of Change
CIE	String	Customer Initiated Entries
RCK	String	Re-presented Check Entries
POS	String	Point of Sale

Resolution Codes

Code	Data Type	Description
DATA_UPDATED	String	The resolution involved updating account data.
JOB_REQUIRED	String	A new Instant Account Verification aggregation is required for resolution.
ACCOUNT_LIMITATION	String	The return is due to an account-level limitation (for example, account type, transaction limits).
NOTICE_OF_CHANGE	String	The return is a Notice of Change (NOC) - informational, but contains corrected data.
UNRESOLVABLE_RETURN	String	The return could not be resolved by MX.
CLIENT_ACTION_REQUIRED	String	Client action is needed.
INVALID_SUBMISSION	String	The API submission was invalid.

Return Codes

Code	Data Type	Title
RETURN_CODE_UNSPECIFIED	String	Use to create an ACH return if you don't have a return code for an ACH return.
R01	String	Insufficient Funds
R02	String	Account Closed
R03	String	No Account / Unable to Locate Account
R04	String	Invalid Account Number Structure
R05	String	Unauthorized Consumer Debit using Corporate SEC Code
R06	String	ODFI Requested Return
R07	String	Customer Revoked Authorization
R08	String	Payment Stopped
R09	String	Uncollected Funds
R10	String	Originator not known and/or not authorized to Debit Receiver’s Account
R11	String	Customer advises not within Authorization Terms
R12	String	Account Sold to Another DFI
R13	String	Invalid ACH Routing No.
R14	String	Representative Payee Deceased
R15	String	Beneficiary / Account Holder Deceased
R16	String	Account Frozen / Returned per OFAC
R17	String	File Record Edit Criteria / Suspicious Entry with Invalid Account No. / Return of Improperly-Initiated Reversal
R18	String	Improper Effective Date
R19	String	Amount Field Error
R20	String	Non-Transaction Account

Return Status

Status	Data Type	Description
RETURN_STATUS_UNSPECIFIED	String	Used if no other return status is set.
SUBMITTED	String	The initial status after you successfully submit ACH return data using the API.
PENDING	String	The submitted return is queued and awaiting automated processing.
PROCESSING	String	The return is currently being actively processed, either by the automated system or by manual review.
RESOLVED_DATA_UPDATED	String	The automated system successfully resolved the return by updating account data in the MX system.
RESOLVED_JOB_REQUIRED	String	The automated system determined that a new Instant Account Verification (IAV) aggregation is required to resolve the return.
RESOLVED_INFORMATIONAL	String	After automated or manual investigation, it's determined that the return reason is due to client-side issues or informational (like account restrictions) and no MX data fix is needed.
RESOLVED_UNRESOLVABLE	String	After thorough automated and/or manual investigation, no resolution is found within MX systems or via data providers.
PENDING_CLIENT_ACTION	String	MX requires action from you to proceed with the return investigation or resolution. This could occur if there was missing data in the submission.
REJECTED	String	The initial API submission was rejected due to errors in the data you provided.